Package org.apache.qpid.protonj2.engine

Interface OutgoingDelivery

  • All Known Implementing Classes:
    ProtonOutgoingDelivery
    public interface OutgoingDelivery
    API for an outgoing Delivery.

    • Method Detail

      • 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​(java.lang.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:
        java.lang.ClassCastException - if the linked resource cannot be cast to the type requested.

      • 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:
        java.lang.IllegalStateException - if the delivery has already written Transfer frames.

      • 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:
        java.lang.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:
        java.lang.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.

      • 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.

      • 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.