org.apache.qpid.proton.engine.Receiver Maven / Gradle / Ivy
/*
*
* 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.proton.engine;
import org.apache.qpid.proton.codec.ReadableBuffer;
import org.apache.qpid.proton.codec.WritableBuffer;
/**
* Receiver
*
*/
public interface Receiver extends Link
{
/**
* Adds the specified number of credits.
*
* The number of link credits initialises to zero. It is the application's responsibility to call
* this method to allow the receiver to receive {@code credits} more deliveries.
*/
public void flow(int credits);
/**
* Receive message data for the current delivery.
*
* If the caller takes all the bytes the Receiver currently has for this delivery then it is removed from
* the Connection's work list.
*
* Before considering a delivery to be complete, the caller should examine {@link Delivery#isPartial()}. If
* the delivery is partial, the caller should call {@link #recv(byte[], int, int)} again to receive
* the additional bytes once the Delivery appears again on the Connection work-list.
*
* TODO might the flags other than IO_WORK in DeliveryImpl also prevent the work list being pruned?
* e.g. what if a slow JMS consumer receives a disposition frame containing state=RELEASED? This is not IO_WORK.
*
* @param bytes the destination array where the message data is written
* @param offset index in the array to start writing data at
* @param size the maximum number of bytes to write
*
* @return number of bytes written. -1 if there are no more bytes for the current delivery.
*
* @see #current()
*/
public int recv(byte[] bytes, int offset, int size);
/**
* Receive message data for the current delivery.
*
* @param buffer the buffer to write the message data.
*
* @return number of bytes written. -1 if there are no more bytes for the current delivery.
*/
public int recv(WritableBuffer buffer);
/**
* Receive message data for the current delivery returning the data in a Readable buffer.
*
* The delivery will return an empty buffer if there is no pending data to be read or if all
* data has been read either by a previous call to this method or by a call to one of the other
* receive methods.
*
* @return a ReadableBuffer that contains the currently available data for the current delivery.
*/
public ReadableBuffer recv();
public void drain(int credit);
/**
* {@inheritDoc}
*
* TODO document what this method conceptually does and when you should use it.
*/
@Override
public boolean advance();
public boolean draining();
public void setDrain(boolean drain);
}