Package org.apache.qpid.protonj2.engine

Interface OutgoingDelivery

All Known Implementing Classes:

ProtonOutgoingDelivery

public interface OutgoingDelivery

API for an outgoing Delivery.

Method Summary

Modifier and Type	Method	Description
OutgoingDelivery	abort()	Aborts the outgoing delivery if not already settled.
OutgoingDelivery	deliveryStateUpdatedHandler(EventHandler<OutgoingDelivery> handler)	Handler for updates to the remote state of outgoing deliveries that have begun transferring frames.
OutgoingDelivery	disposition(DeliveryState state)	updates the state of the delivery
OutgoingDelivery	disposition(DeliveryState state, boolean settle)	Update the delivery with the given disposition if not locally settled and optionally settles the delivery if not already settled.
Attachments	getAttachments()
Sender	getLink()
<T> T	getLinkedResource()
<T> T	getLinkedResource(Class<T> typeClass)	Gets the linked resource (if set) and returns it using the type information provided to cast the returned value.
int	getMessageFormat()	Gets the message-format for this Delivery, representing the 32bit value using an int.
DeliveryState	getRemoteState()
DeliveryState	getState()
DeliveryTag	getTag()
int	getTransferCount()	Returns the total number of transfer frames that have occurred for the given OutgoingDelivery.
boolean	isAborted()
boolean	isPartial()	Check for whether the delivery is still partial.
boolean	isRemotelySettled()
boolean	isSettled()
OutgoingDelivery	setLinkedResource(Object resource)	Links a given resource to this Endpoint.
OutgoingDelivery	setMessageFormat(int messageFormat)	Sets the message-format for this Delivery, representing the 32bit value using an integer value.
OutgoingDelivery	setTag(byte[] deliveryTag)	Sets the delivery tag to assign to this outgoing delivery from the given byte array.
OutgoingDelivery	setTag(DeliveryTag deliveryTag)	Sets the DeliveryTag to assign to this outgoing delivery.
OutgoingDelivery	settle()	Settles this delivery if not already settled.
OutgoingDelivery	streamBytes(ProtonBuffer buffer)	Write the given bytes as a portion of the payload of this delivery, additional bytes can be streamed until the stream complete flag is set to true on a call to streamBytes(ProtonBuffer, boolean) or a call to writeBytes(ProtonBuffer) is made.
OutgoingDelivery	streamBytes(ProtonBuffer buffer, boolean complete)	Write the given bytes as a portion of the payload of this delivery, additional bytes can be streamed until the stream complete flag is set to true on a call to streamBytes(ProtonBuffer, boolean) and the buffer contents on that send are fully written.
OutgoingDelivery	writeBytes(ProtonBuffer buffer)	Write the given bytes as the payload of this delivery, no additional writes can occur on this delivery if the write succeeds in sending all of the given bytes.

Method Detail

getLink

Sender getLink()

Returns:

the link that this OutgoingDelivery is bound to.

getAttachments

Attachments getAttachments()

Returns:

the Attachments instance that is associated with this OutgoingDelivery

setLinkedResource

OutgoingDelivery setLinkedResource(Object resource)

Links a given resource to this Endpoint.

Parameters:

resource - The resource to link to this Endpoint.

Returns:

this OutgoingDelivery instance.

getLinkedResource

<T> T getLinkedResource()

Type Parameters:

T - The type that the linked resource should be cast to on return.

Returns:

the user set linked resource for this Endpoint instance.

getLinkedResource

<T> T getLinkedResource(Class<T> typeClass)

Gets the linked resource (if set) and returns it using the type information provided to cast the returned value.

Type Parameters:

T - The type to cast the linked resource to if one is set.

Parameters:

typeClass - the type's Class which is used for casting the returned value.

Returns:

the user set linked resource for this Context instance.

Throws:

ClassCastException - if the linked resource cannot be cast to the type requested.

getMessageFormat

int getMessageFormat()

Gets the message-format for this Delivery, representing the 32bit value using an int.

The default value is 0 as per the message format defined in the core AMQP 1.0 specification.

See the following for more details:
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-transfer
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-message-format
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#definition-MESSAGE-FORMAT

Returns:

the message-format for this Delivery.

setMessageFormat

OutgoingDelivery setMessageFormat(int messageFormat)

Sets the message-format for this Delivery, representing the 32bit value using an integer value. The message format can only be set@Override prior to the first Transfer of delivery payload having been written. If one of the delivery write methods is called prior to the message format being set then it defaults to the AMQP default format of zero.

The default value is 0 as per the message format defined in the core AMQP 1.0 specification.

See the following for more details:
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-transfer
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-message-format
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format
http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#definition-MESSAGE-FORMAT

Parameters:

messageFormat - the message format

Returns:

this OutgoingDelivery instance.

Throws:

IllegalStateException - if the delivery has already written Transfer frames.

getTag

DeliveryTag getTag()

Returns:

the DeliveryTag assigned to this Delivery.

setTag

OutgoingDelivery setTag(byte[] deliveryTag)

Sets the delivery tag to assign to this outgoing delivery from the given byte array.

Parameters:

deliveryTag - a byte array containing the delivery tag to assign to this OutgoingDelivery

Returns:

this OutgoingDelivery instance.

Throws:

IllegalStateException - if the delivery has already written Transfer frames.

setTag

OutgoingDelivery setTag(DeliveryTag deliveryTag)

Sets the DeliveryTag to assign to this outgoing delivery.

Parameters:

deliveryTag - a byte array containing the delivery tag to assign to this OutgoingDelivery

Returns:

this OutgoingDelivery instance.

isPartial

boolean isPartial()

Check for whether the delivery is still partial.

For a receiving Delivery, this means the delivery does not hold a complete message payload as all the content hasn't been received yet. Note that an aborted delivery will also be considered partial and the full payload won't be received.

For a sending Delivery, this means that the application has not marked the delivery as complete yet.

Returns:

true if the delivery is partial

See Also:

isAborted()

writeBytes

OutgoingDelivery writeBytes(ProtonBuffer buffer)

Write the given bytes as the payload of this delivery, no additional writes can occur on this delivery if the write succeeds in sending all of the given bytes.

When called the provided buffer is treated as containing the entirety of the transfer payload and the Transfer(s) that result from this call will result in a final Transfer frame whose more flag is set to false which tells the remote that no additional data will be sent for this Transfer. The Sender will output as much of the buffer as possible within the constraints of both the link credit and the current capacity of the parent Session.

The caller must check that all bytes were written and if not they should await updates from the Link.creditStateUpdateHandler(EventHandler) that indicate that the Sender.isSendable() has become true again or the caller should check Sender.isSendable() periodically until it becomes true once again.

Parameters:

buffer - The buffer whose contents should be sent.

Returns:

this OutgoingDelivery instance.

Throws:

IllegalStateException - if the parent Sender link becomes inoperable due to closure or failure.

streamBytes

OutgoingDelivery streamBytes(ProtonBuffer buffer)

Write the given bytes as a portion of the payload of this delivery, additional bytes can be streamed until the stream complete flag is set to true on a call to streamBytes(ProtonBuffer, boolean) or a call to writeBytes(ProtonBuffer) is made.

The Sender will output as much of the buffer as possible within the constraints of both the link credit and the current capacity of the parent Session. The caller must check that all bytes were0 written and if not they should await updates from the Link.creditStateUpdateHandler(EventHandler) that indicate that the Sender.isSendable() has become true again or the caller should check Sender.isSendable() periodically until it becomes true once again.

This method is the same as calling streamBytes(ProtonBuffer, boolean) with the complete value set to false.

Parameters:

buffer - The buffer whose contents should be sent.

Returns:

this OutgoingDelivery instance.

Throws:

IllegalStateException - if the parent Sender link becomes inoperable due to closure or failure.

streamBytes

OutgoingDelivery streamBytes(ProtonBuffer buffer,
                             boolean complete)

Write the given bytes as a portion of the payload of this delivery, additional bytes can be streamed until the stream complete flag is set to true on a call to streamBytes(ProtonBuffer, boolean) and the buffer contents on that send are fully written.

The Sender will output as much of the buffer as possible within the constraints of both the link credit and the current capacity of the parent Session. The caller must check that all bytes were0 written and if not they should await updates from the Link.creditStateUpdateHandler(EventHandler) that indicate that the Sender.isSendable() has become true again or the caller should check Sender.isSendable() periodically until it becomes true once again.

Parameters:

buffer - The buffer whose contents should be sent.

complete - When true the delivery is marked complete and no further bytes can be written.

Returns:

this OutgoingDelivery instance.

Throws:

IllegalStateException - if the parent Sender link becomes inoperable due to closure or failure.

isAborted

boolean isAborted()

Returns:

true if the delivery has been aborted.

abort

OutgoingDelivery abort()

Aborts the outgoing delivery if not already settled.

Returns:

this delivery.

getState

DeliveryState getState()

Returns:

the DeliveryState at the local side of this Delivery.

disposition

OutgoingDelivery disposition(DeliveryState state)

updates the state of the delivery

Parameters:

state - the new delivery state

Returns:

this OutgoingDelivery instance.

disposition

OutgoingDelivery disposition(DeliveryState state,
                             boolean settle)

Update the delivery with the given disposition if not locally settled and optionally settles the delivery if not already settled.

The action taken by this method depends on the state of the OutgoingDelivery at the time it is called.

If there has yet to be any writes from this delivery the delivery state and settlement value is cached and applied to the first (or only) write of payload from this delivery. If however a write has already been performed than this method result in a Disposition frame being sent to the remote with the given delivery state and settlement value. Once the delivery is marked as settled any future call to this method will do nothing if the requested disposition and settlement is the same however if a new state is applied which cannot be conveyed due to having already locally settling the OutgoingDelivery than an IllegalStateException is thrown to indicate that request is not valid.

Parameters:

state - the new delivery state

settle - if true the delivery is settled.

Returns:

this OutgoingDelivery instance.

isSettled

boolean isSettled()

Returns:

true if the delivery has been settled locally.

settle

OutgoingDelivery settle()

Settles this delivery if not already settled. Once settled locally no further updates to the delivery state can be applied. If called prior to the first write of payload bytes the settlement state is cached and transmitted within the first Transfer frame of this OutgoingDelivery.

Returns:

this OutgoingDelivery instance.

isRemotelySettled

boolean isRemotelySettled()

Returns:

true if the delivery has been settled by the remote.

getRemoteState

DeliveryState getRemoteState()

Returns:

the DeliveryState at the remote side of this Delivery.

getTransferCount

int getTransferCount()

Returns the total number of transfer frames that have occurred for the given OutgoingDelivery. If the OutgoingDelivery has yet to have any of its write methods called this value will read zero. Aborting a transfer after any Transfer frames have been written will not result in an addition recorded Transfer write.

Returns:

the number of Transfer frames that this OutgoingDelivery has initiated.

deliveryStateUpdatedHandler

OutgoingDelivery deliveryStateUpdatedHandler(EventHandler<OutgoingDelivery> handler)

Handler for updates to the remote state of outgoing deliveries that have begun transferring frames.

Remote state updates for an OutgoingDelivery can happen when the remote settles a complete OutgoingDelivery or otherwise modifies the delivery outcome and the user needs to act on those changes such as a spontaneous update to the DeliveryState. If the initial Transfer of an outgoing delivery already indicates settlement then this handler will never be called.

Parameters:

handler - The handler that will be invoked when a new remote state update for an OutgoingDelivery arrives on this link.

Returns:

this OutgoingDelivery instance.