| /* |
| * |
| * 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.messenger; |
| |
| import java.io.IOException; |
| import java.util.concurrent.TimeoutException; |
| |
| import org.apache.qpid.proton.message.Message; |
| |
| /** |
| * |
| * Messenger defines a high level interface for sending and receiving |
| * messages. Every Messenger contains a single logical queue of |
| * incoming messages and a single logical queue of outgoing |
| * messages. These messages in these queues may be destined for, or |
| * originate from, a variety of addresses. |
| * |
| * <h3>Address Syntax</h3> |
| * |
| * An address has the following form: |
| * |
| * [ amqp[s]:// ] [user[:password]@] domain [/[name]] |
| * |
| * Where domain can be one of: |
| * |
| * host | host:port | ip | ip:port | name |
| * |
| * The following are valid examples of addresses: |
| * |
| * - example.org |
| * - example.org:1234 |
| * - amqp://example.org |
| * - amqps://example.org |
| * - example.org/incoming |
| * - amqps://example.org/outgoing |
| * - amqps://fred:trustno1@example.org |
| * - 127.0.0.1:1234 |
| * - amqps://127.0.0.1:1234 |
| * |
| * <h3>Sending & Receiving Messages</h3> |
| * |
| * The Messenger interface works in conjuction with the Message |
| * class. The Message class is a mutable holder of message content. |
| * The put method will encode the content in a given Message object |
| * into the outgoing message queue leaving that Message object free |
| * to be modified or discarded without having any impact on the |
| * content in the outgoing queue. |
| * |
| * Similarly, the get method will decode the content in the incoming |
| * message queue into the supplied Message object. |
| */ |
| public interface Messenger |
| { |
| /** |
| * Flag for use with reject(), accept() and settle() methods. |
| */ |
| static final int CUMULATIVE = 0x01; |
| |
| /** |
| * Places the content contained in the message onto the outgoing |
| * queue of the Messenger. This method will never block. The |
| * send call may be used to block until the messages are |
| * sent. Either a send() or a recv() call is neceesary at present |
| * to cause the messages to actually be sent out. |
| */ |
| void put(Message message) throws MessengerException; |
| /** |
| * Blocks until the outgoing queue is empty and, in the event that |
| * an outgoing window has been set, until the messages in that |
| * window have been received by the target to which they were |
| * sent, or the operation times out. The timeout property |
| * controls how long a Messenger will block before timing out. |
| */ |
| void send() throws TimeoutException; |
| |
| /** |
| * Subscribes the Messenger to messages originating from the |
| * specified source. The source is an address as specified in the |
| * Messenger introduction with the following addition. If the |
| * domain portion of the address begins with the '~' character, |
| * the Messenger will interpret the domain as host/port, bind |
| * to it, and listen for incoming messages. For example |
| * "~0.0.0.0", "amqp://~0.0.0.0" will bind to any local interface |
| * and listen for incoming messages. |
| */ |
| void subscribe(String source) throws MessengerException; |
| /** |
| * Receives up to the specified number of messages into the |
| * incoming queue of the Messenger. This method will block until |
| * at least one message is available or the operation times out. |
| */ |
| void recv(int count) throws TimeoutException; |
| /** |
| * Returns the message from the head of the incoming message |
| * queue. |
| */ |
| Message get(); |
| |
| /** |
| * Transitions the Messenger to an active state. A Messenger is |
| * initially created in an inactive state. When inactive, a |
| * Messenger will not send or receive messages from its internal |
| * queues. A Messenger must be started before calling send() or |
| * recv(). |
| */ |
| void start() throws IOException; |
| /** |
| * Transitions the Messenger to an inactive state. An inactive |
| * Messenger will not send or receive messages from its internal |
| * queues. A Messenger should be stopped before being discarded to |
| * ensure a clean shutdown handshake occurs on any internally managed |
| * connections. |
| */ |
| void stop(); |
| |
| void setTimeout(long timeInMillis); |
| long getTimeout(); |
| |
| /** |
| * Returns a count of the messages currently on the outgoing queue |
| * (i.e. those that have been put() but not yet actually sent |
| * out). |
| */ |
| int outgoing(); |
| /** |
| * Returns a count of the messages available on the incoming |
| * queue. |
| */ |
| int incoming(); |
| |
| int getIncomingWindow(); |
| void setIncomingWindow(int window); |
| |
| int getOutgoingWindow(); |
| void setOutgoingWindow(int window); |
| |
| /** |
| * Returns a token which can be used to accept or reject the |
| * message returned in the previous get() call. |
| */ |
| Tracker incomingTracker(); |
| /** |
| * Returns a token which can be used to track the status of the |
| * message of the previous put() call. |
| */ |
| Tracker outgoingTracker(); |
| |
| /** |
| * Rejects messages retrieved from the incoming message queue. The |
| * tracker object for a message is obtained through a call to |
| * incomingTracker() following a get(). If the flags argument |
| * contains CUMULATIVE, then all message up to the one identified |
| * by the tracker will be rejected. |
| */ |
| void reject(Tracker tracker, int flags); |
| /** |
| * Accepts messages retrieved from the incoming message queue. The |
| * tracker object for a message is obtained through a call to |
| * incomingTracker() following a get(). If the flags argument |
| * contains CUMULATIVE, then all message up to the one identified |
| * by the tracker will be accepted. |
| */ |
| void accept(Tracker tracker, int flags); |
| void settle(Tracker tracker, int flags); |
| |
| /** |
| * Gets the last known remote state of the delivery associated |
| * with the given tracker. |
| */ |
| Status getStatus(Tracker tracker); |
| } |