From 47ae817a3ba9fa14657808b6319bafb62d7c66ba Mon Sep 17 00:00:00 2001 From: Arnaud Simon Date: Tue, 7 Aug 2007 07:49:42 +0000 Subject: changed messageFlush to return an int git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@563416 13f79535-47bb-0310-9956-ffa450edef68 --- .../java/org/apache/qpidity/client/Session.java | 972 ++++++++++----------- 1 file changed, 483 insertions(+), 489 deletions(-) (limited to 'java/client/src') diff --git a/java/client/src/main/java/org/apache/qpidity/client/Session.java b/java/client/src/main/java/org/apache/qpidity/client/Session.java index b2d7c5705e..eddee6cba1 100644 --- a/java/client/src/main/java/org/apache/qpidity/client/Session.java +++ b/java/client/src/main/java/org/apache/qpidity/client/Session.java @@ -1,489 +1,483 @@ -/* - * 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.qpidity.client; - -import java.util.Map; - -import org.apache.qpidity.QpidException; -import org.apache.qpidity.Option; -import org.apache.qpidity.Header; -import org.apache.qpidity.Range; -import org.apache.qpidity.api.Message; - -/** - *

A session is associated with a connection. - * When created a Session is not attached with an underlying channel. - * Session is single threaded

- */ -public interface Session -{ - public static final short ACQUIRE_MODE_NO_ACQUIRE = 0; - public static final short ACQUIRE_MODE_PRE_ACQUIRE = 1; - public static final short CONFIRM_MODE_REQUIRED = 1; - public static final short CONFIRM_MODE_NOT_REQUIRED = 0; - public static final short MESSAGE_FLOW_MODE_CREDIT = 0; - public static final short MESSAGE_FLOW_MODE_WINDOW = 1; - public static final short MESSAGE_FLOW_UNIT_MESSAGE = 0; - public static final short MESSAGE_FLOW_UNIT_BYTE = 1; - - //------------------------------------------------------ - // Session housekeeping methods - //------------------------------------------------------ - /** - * Close this session and any associated resources. - * - * @throws QpidException If the communication layer fails to close this session or if an internal error happens - * when closing this session resources. . - */ - public void close() throws QpidException; - - /** - * Suspend this session resulting in interrupting the traffic with the broker. - *

The session timer will start to tick in suspend. - *

When a session is suspend any operation of this session and of the associated resources are unavailable. - * - * @throws QpidException If the communication layer fails to suspend this session - */ - public void suspend() throws QpidException; - - /** - * This will resume an existing session - *

Upon resume the session is attached with an underlying channel - * hence making operation on this session available. - * - * @throws QpidException If the communication layer fails to execute this properly - */ - public void resume() throws QpidException; - - //------------------------------------------------------ - // Messaging methods - // Producer - //------------------------------------------------------ - /** - * Transfer the given message to a specified exchange. - * - * @param confirmMode

- * @param acquireMode - * @param exchange The exchange the message is being sent. - * @param msg The Message to be sent - * @throws QpidException If the session fails to send the message due to some error - */ - public void messageTransfer(String exchange, Message msg, short confirmMode, short acquireMode) throws QpidException; - - /** - * Declare the beginning of a message transfer operation. This operation must - * be followed by {@link Session#addMessageHeaders} then followed by any number of {@link Session#addData}. - * The transfer is ended by endData. - *

This way of transferring messages is useful when streaming large messages - *

In the interval [messageTransfer endData] any attempt to call a method other than - * {@link Session#addMessageHeaders}, {@link Session#endData} ore {@link Session#close} - * will result in an exception being thrown. - * - * @param confirmMode

- * @param acquireMode - * @param exchange The exchange the message is being sent. - * @throws QpidException If the session fails to send the message due to some error. - */ - public void messageTransfer(String exchange, short confirmMode, short acquireMode) throws QpidException; - - /** - * Add the following headers ( {@link org.apache.qpidity.DeliveryProperties} - * or to the message being sent. - * - * @param headers Either DeliveryProperties or ApplicationProperties - * @throws QpidException If the session fails to execute the method due to some error - * @see org.apache.qpidity.DeliveryProperties - */ - public void addMessageHeaders(Header... headers) throws QpidException; - - /** - * Add the following byte array to the content of the message being sent. - * - * @param data Data to be added. - * @param off Offset from which to start reading data - * @param len Number of bytes to be read - * @throws QpidException If the session fails to execute the method due to some error - */ - public void addData(byte[] data, int off, int len) throws QpidException; - - /** - * Signals the end of data for the message. - * - * @throws QpidException If the session fails to execute the method due to some error - */ - public void endData() throws QpidException; - - //------------------------------------------------------ - // Messaging methods - // Consumer - //------------------------------------------------------ - - /** - * Associate a message listener with a destination. - *

The destination is bound to a queue and messages are filtered based - * on the provider filter map (message filtering is specific to the provider and may not be handled). - *

- *

Following are the valid options - *

- *

In the absence of a particular option, defaul values are: - *

- * - * @param queue The queue this receiver is receiving messages from. - * @param destination The destination for the subscriber ,a.k.a the delivery tag. - * @param confirmMode - * @param acquireMode - * @param listener The listener for this destination. When big message are transfered then - * it is recommended to use a {@link MessagePartListener}. - * @param options Set of Options. - * @param filter A set of filters for the subscription. The syntax and semantics of these filters depends - * on the providers implementation. - * @throws QpidException If the session fails to create the receiver due to some error. - */ - public void messageSubscribe(String queue, String destination, short confirmMode, short acquireMode, - MessagePartListener listener, Map filter, Option... options) - throws QpidException; - - /** - * This method cancels a consumer. This does not affect already delivered messages, but it does - * mean the server will not send any more messages for that destination. The client may receive an - * arbitrary number of messages in between sending the cancel method and receiving the - * notification of completion of the cancel command. - * - * @param destination The destination for the subscriber used at subscription - * @throws QpidException If cancelling the subscription fails due to some error. - */ - public void messageCancel(String destination) throws QpidException; - - /** - * Associate a message part listener with a destination. - * We currently allow one listerner per destination this means - * that the previous message listener is replaced. This is done gracefully i.e. the message - * listener is replaced once it return from the processing of a message. - * - * @param destination The destination the listener is associated with. - * @param listener The new listener for this destination. - */ - public void setMessageListener(String destination, MessagePartListener listener); - - /** - * Sets the mode of flow control used for a given destination. - *

- * With credit based flow control, the broker continually maintains its current - * credit balance with the recipient. The credit balance consists of two values, a message - * count, and a byte count. Whenever message data is sent, both counts must be decremented. - * If either value reaches zero, the flow of message data must stop. Additional credit is - * received via the {@link Session#messageFlow} method. - *

- * Window based flow control is identical to credit based flow control, however message - * acknowledgment implicitly grants a single unit of message credit, and the size of the - * message in byte credits for each acknowledged message. - * - * @param destination The destination to set the flow mode on. - * @param mode

- * @throws QpidException If setting the flow mode fails due to some error. - */ - public void messageFlowMode(String destination, short mode) throws QpidException; - - - /** - * This method controls the flow of message data to a given destination. It is used by the - * recipient of messages to dynamically match the incoming rate of message flow to its - * processing or forwarding capacity. Upon receipt of this method, the sender must add "value" - * number of the specified unit to the available credit balance for the specified destination. - * A value of 0 indicates an infinite amount of credit. This disables any limit for - * the given unit until the credit balance is zeroed with {@link Session#messageStop} - * or {@link Session#messageFlush}. - * - * @param destination The destination to set the flow. - * @param unit Specifies the unit of credit balance. - *

- * One of:

- * @param value Number of credits, a value of 0 indicates an infinite amount of credit. - * @throws QpidException If setting the flow fails due to some error. - */ - public void messageFlow(String destination, short unit, long value) throws QpidException; - - /** - * Forces the broker to exhaust its credit supply. - *

The broker's credit will always be zero when - * this method completes. This method does not complete until all the message transfers occur. - *

This method returns true if messages have been flushed - * (i.e. the queue was not empty and the credit greater then zero). - * It returns false if the queue was empty. - * - * @param destination The destination to call flush on. - * @return True is messages were flushed, false otherwise. - * @throws QpidException If flushing fails due to some error. - */ - public boolean messageFlush(String destination) throws QpidException; - - /** - * On receipt of this method, the brokers MUST set his credit to zero for the given - * destination. This obeys the generic semantics of command completion, i.e. when confirmation - * is issued credit MUST be zero and no further messages will be sent until such a time as - * further credit is received. - * - * @param destination The destination to stop. - * @throws QpidException If stopping fails due to some error. - */ - public void messageStop(String destination) throws QpidException; - - /** - * Acknowledge the receipt of ranges of messages. - *

Message must have been previously acquired either by receiving them in - * pre-acquire mode or by explicitly acquiring them. - * - * @param range Range of acknowledged messages. - * @throws QpidException If the acknowledgement of the messages fails due to some error. - */ - public void messageAcknowledge(Range... range) throws QpidException; - - /** - * Reject ranges of acquired messages. - *

A rejected message will not be delivered to any receiver - * and may be either discarded or moved to the broker dead letter queue. - * - * @param range Range of rejected messages. - * @throws QpidException If those messages cannot be rejected dus to some error - */ - public void messageReject(Range... range) throws QpidException; - - /** - * Try to acquire ranges of messages hence releasing them form the queue. - * This means that once acknowledged, a message will not be delivered to any other receiver. - *

As those messages may have been consumed by another receivers hence, - * message acquisition can fail. - * The outcome of the acquisition is returned as an array of ranges of qcquired messages. - *

This method should only be called on non-acquired messages. - * - * @param range Ranges of messages to be acquired. - * @return Ranges of explicitly acquired messages. - * @throws QpidException If this message cannot be acquired dus to some error - */ - public Range[] messageAcquire(Range... range) throws QpidException; - - /** - * Give up responsibility for processing ranges of messages. - *

Released messages are re-enqueued. - * - * @param range Ranges of messages to be released. - * @throws QpidException If this message cannot be released dus to some error. - */ - public void messageRelease(Range... range) throws QpidException; - - // ----------------------------------------------- - // Local transaction methods - // ---------------------------------------------- - /** - * Selects the session for local transaction support. - * - * @throws QpidException If selecting this session for local transaction support fails due to some error. - */ - public void txSelect() throws QpidException; - - /** - * Commit the receipt and the delivery of all messages exchanged by this session resources. - * - * @throws QpidException If the session fails to commit due to some error. - * @throws IllegalStateException If this session is not transacted. - */ - public void txCommit() throws QpidException, IllegalStateException; - - /** - * Rollback the receipt and the delivery of all messages exchanged by this session resources. - * - * @throws QpidException If the session fails to rollback due to some error. - * @throws IllegalStateException If this session is not transacted. - */ - public void txRollback() throws QpidException, IllegalStateException; - - //--------------------------------------------- - // Queue methods - //--------------------------------------------- - - /** - * Declare a queue with the given queueName - *

Following are the valid options for declareQueue - *

- *

- *

- *

In the absence of a particular option, the defaul value is false for each option - * - * @param queueName The name of the delcared queue. - * @param alternateExchange If a message is rejected by a queue, then it is sent to the alternate-exchange. A message - * may be rejected by a queue for the following reasons: - *

  1. The queue is deleted when it is not empty; - * <
  2. Immediate delivery of a message is requested, but there are no consumers connected to - * the queue.
- * @param arguments Used for backward compatibility - * @param options Set of Options. - * @throws QpidException If the session fails to declare the queue due to some error. - * @see Option - */ - public void queueDeclare(String queueName, String alternateExchange, Map arguments, Option... options) - throws QpidException; - - /** - * Bind a queue with an exchange. - * - * @param queueName The queue to be bound. - * @param exchangeName The exchange name. - * @param routingKey The routing key. - * @param arguments Used for backward compatibility - * @throws QpidException If the session fails to bind the queue due to some error. - */ - public void queueBind(String queueName, String exchangeName, String routingKey, Map arguments) - throws QpidException; - - /** - * Unbind a queue from an exchange. - * - * @param queueName The queue to be unbound. - * @param exchangeName The exchange name. - * @param routingKey The routing key. - * @param arguments Used for backward compatibility - * @throws QpidException If the session fails to unbind the queue due to some error. - */ - public void queueUnbind(String queueName, String exchangeName, String routingKey, Map arguments) - throws QpidException; - - /** - * Purge a queue. i.e. delete all enqueued messages - * - * @param queueName The queue to be purged - * @throws QpidException If the session fails to purge the queue due to some error. - */ - public void queuePurge(String queueName) throws QpidException; - - /** - * Delet a queue. - *

Following are the valid options for createReceive - *

    - *
  • IF_EMPTY - *
  • IF_UNUSE - *
  • NO_WAIT - *
- *

- *

- *

In the absence of a particular option, the defaul value is false for each option

- * - * @param queueName The name of the queue to be deleted - * @param options Set of options - * @throws QpidException If the session fails to delete the queue due to some error. - * @see Option - *

- * Following are the valid options - */ - public void queueDelete(String queueName, Option... options) throws QpidException; - - // -------------------------------------- - // exhcange methods - // -------------------------------------- - - /** - * Declare an exchange. - *

Following are the valid options for createReceive - *

    - *
  • AUTO_DELETE - *
  • DURABLE - *
  • INTERNAL - *
  • NO_WAIT - *
  • PASSIVE - *
- *

- *

- *

In the absence of a particular option, the defaul value is false for each option

* - * - * @param exchangeName The exchange name. - * @param exchangeClass The fully qualified name of the exchange class. - * @param alternateExchange In the event that a message cannot be routed, this is the name of the exchange to which - * the message will be sent. - * @param options Set of options. - * @param arguments Used for backward compatibility - * @throws QpidException If the session fails to declare the exchange due to some error. - * @see Option - */ - public void exchangeDeclare(String exchangeName, String exchangeClass, String alternateExchange, - Map arguments, Option... options) throws QpidException; - - /** - * Delete an exchange. - *

Following are the valid options for createReceive - *

    - *
  • IF_UNUSEDL - *
  • NO_WAIT - *
- *

- *

- *

In the absence of a particular option, the defaul value is false for each option - * Immediately deleted even if it is used by another resources.

- * - * @param exchangeName The name of exchange to be deleted. - * @param options Set of options. - * @throws QpidException If the session fails to delete the exchange due to some error. - * @see Option - */ - public void exchangeDelete(String exchangeName, Option... options) throws QpidException; -} +/* + * 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.qpidity; + +import java.util.Map; + +import org.apache.qpidity.api.Message; + +/** + *

A session is associated with a connection. + * When created a Session is not attached with an underlying channel. + * Session is single threaded

+ */ +public interface Session +{ + public static final short ACQUIRE_MODE_NO_ACQUIRE = 0; + public static final short ACQUIRE_MODE_PRE_ACQUIRE = 1; + public static final short CONFIRM_MODE_REQUIRED = 1; + public static final short CONFIRM_MODE_NOT_REQUIRED = 0; + public static final short MESSAGE_FLOW_MODE_CREDIT = 0; + public static final short MESSAGE_FLOW_MODE_WINDOW = 1; + public static final short MESSAGE_FLOW_UNIT_MESSAGE = 0; + public static final short MESSAGE_FLOW_UNIT_BYTE = 1; + + //------------------------------------------------------ + // Session housekeeping methods + //------------------------------------------------------ + /** + * Close this session and any associated resources. + * + * @throws QpidException If the communication layer fails to close this session or if an internal error happens + * when closing this session resources. . + */ + public void close() throws QpidException; + + /** + * Suspend this session resulting in interrupting the traffic with the broker. + *

The session timer will start to tick in suspend. + *

When a session is suspend any operation of this session and of the associated resources are unavailable. + * + * @throws QpidException If the communication layer fails to suspend this session + */ + public void suspend() throws QpidException; + + /** + * This will resume an existing session + *

Upon resume the session is attached with an underlying channel + * hence making operation on this session available. + * + * @throws QpidException If the communication layer fails to execute this properly + */ + public void resume() throws QpidException; + + //------------------------------------------------------ + // Messaging methods + // Producer + //------------------------------------------------------ + /** + * Transfer the given message to a specified exchange. + * + * @param confirmMode

    off (0): confirmation is not required, once a message has been transferred in pre-acquire + * mode (or once acquire has been sent in no-acquire mode) the message is considered + * transferred + *

    + *

  • on (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or + * explicit as in no-acquire mode) is not considered transferred until the original + * transfer is complete (signaled via execution.complete) + *
+ * @param acquireMode
  • no-acquire (0): the message must be explicitly acquired + *

    + *

  • pre-acquire (1): the message is acquired when the transfer starts + *
+ * @param exchange The exchange the message is being sent. + * @param msg The Message to be sent + * @throws QpidException If the session fails to send the message due to some error + */ + public void messageTransfer(String exchange, Message msg, short confirmMode, short acquireMode) throws QpidException; + + /** + * Declare the beginning of a message transfer operation. This operation must + * be followed by {@link Session#addMessageHeaders} then followed by any number of {@link Session#addData}. + * The transfer is ended by endData. + *

This way of transferring messages is useful when streaming large messages + *

In the interval [messageTransfer endData] any attempt to call a method other than + * {@link Session#addMessageHeaders}, {@link Session#endData} ore {@link Session#close} + * will result in an exception being thrown. + * + * @param confirmMode

    off (0): confirmation is not required, once a message has been transferred in pre-acquire + * mode (or once acquire has been sent in no-acquire mode) the message is considered + * transferred + *

    + *

  • on (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or + * explicit as in no-acquire mode) is not considered transferred until the original + * transfer is complete (signaled via execution.complete) + *
+ * @param acquireMode
  • no-acquire (0): the message must be explicitly acquired + *

    + *

  • pre-acquire (1): the message is acquired when the transfer starts + *
+ * @param exchange The exchange the message is being sent. + * @throws QpidException If the session fails to send the message due to some error. + */ + public void messageTransfer(String exchange, short confirmMode, short acquireMode) throws QpidException; + + /** + * Add the following headers ( {@link org.apache.qpidity.DeliveryProperties} + * or to the message being sent. + * + * @param headers Either DeliveryProperties or ApplicationProperties + * @throws QpidException If the session fails to execute the method due to some error + * @see org.apache.qpidity.DeliveryProperties + */ + public void addMessageHeaders(Header... headers) throws QpidException; + + /** + * Add the following byte array to the content of the message being sent. + * + * @param data Data to be added. + * @param off Offset from which to start reading data + * @param len Number of bytes to be read + * @throws QpidException If the session fails to execute the method due to some error + */ + public void addData(byte[] data, int off, int len) throws QpidException; + + /** + * Signals the end of data for the message. + * + * @throws QpidException If the session fails to execute the method due to some error + */ + public void endData() throws QpidException; + + //------------------------------------------------------ + // Messaging methods + // Consumer + //------------------------------------------------------ + + /** + * Associate a message listener with a destination. + *

The destination is bound to a queue and messages are filtered based + * on the provider filter map (message filtering is specific to the provider and may not be handled). + *

+ *

Following are the valid options + *

    + *
  • NO_LOCAL + *
  • EXCLUSIVE + *
+ *

In the absence of a particular option, defaul values are: + *

    + *
  • NO_LOCAL = false + *
  • EXCLUSIVE = false + *
+ * + * @param queue The queue this receiver is receiving messages from. + * @param destination The destination for the subscriber ,a.k.a the delivery tag. + * @param confirmMode
    off (0): confirmation is not required, once a message has been transferred in pre-acquire + * mode (or once acquire has been sent in no-acquire mode) the message is considered + * transferred + *

    + *

  • on (1): an acquired message (whether acquisition was implicit as in pre-acquire mode or + * explicit as in no-acquire mode) is not considered transferred until the original + * transfer is complete (signaled via execution.complete) + *
+ * @param acquireMode
  • no-acquire (0): the message must be explicitly acquired + *

    + *

  • pre-acquire (1): the message is acquired when the transfer starts + *
+ * @param listener The listener for this destination. When big message are transfered then + * it is recommended to use a {@link MessagePartListener}. + * @param options Set of Options. + * @param filter A set of filters for the subscription. The syntax and semantics of these filters depends + * on the providers implementation. + * @throws QpidException If the session fails to create the receiver due to some error. + */ + public void messageSubscribe(String queue, String destination, short confirmMode, short acquireMode, + MessagePartListener listener, Map filter, Option... options) + throws QpidException; + + /** + * This method cancels a consumer. This does not affect already delivered messages, but it does + * mean the server will not send any more messages for that destination. The client may receive an + * arbitrary number of messages in between sending the cancel method and receiving the + * notification of completion of the cancel command. + * + * @param destination The destination for the subscriber used at subscription + * @throws QpidException If cancelling the subscription fails due to some error. + */ + public void messageCancel(String destination) throws QpidException; + + /** + * Associate a message part listener with a destination. + * We currently allow one listerner per destination this means + * that the previous message listener is replaced. This is done gracefully i.e. the message + * listener is replaced once it return from the processing of a message. + * + * @param destination The destination the listener is associated with. + * @param listener The new listener for this destination. + */ + public void setMessageListener(String destination, MessagePartListener listener); + + /** + * Sets the mode of flow control used for a given destination. + *

+ * With credit based flow control, the broker continually maintains its current + * credit balance with the recipient. The credit balance consists of two values, a message + * count, and a byte count. Whenever message data is sent, both counts must be decremented. + * If either value reaches zero, the flow of message data must stop. Additional credit is + * received via the {@link Session#messageFlow} method. + *

+ * Window based flow control is identical to credit based flow control, however message + * acknowledgment implicitly grants a single unit of message credit, and the size of the + * message in byte credits for each acknowledged message. + * + * @param destination The destination to set the flow mode on. + * @param mode

  • credit (0): choose credit based flow control + *
  • window (1): choose window based flow control
+ * @throws QpidException If setting the flow mode fails due to some error. + */ + public void messageFlowMode(String destination, short mode) throws QpidException; + + + /** + * This method controls the flow of message data to a given destination. It is used by the + * recipient of messages to dynamically match the incoming rate of message flow to its + * processing or forwarding capacity. Upon receipt of this method, the sender must add "value" + * number of the specified unit to the available credit balance for the specified destination. + * A value of 0 indicates an infinite amount of credit. This disables any limit for + * the given unit until the credit balance is zeroed with {@link Session#messageStop} + * or {@link Session#messageFlush}. + * + * @param destination The destination to set the flow. + * @param unit Specifies the unit of credit balance. + *

+ * One of:

    + *
  • message (0) + *
  • byte (1) + *
+ * @param value Number of credits, a value of 0 indicates an infinite amount of credit. + * @throws QpidException If setting the flow fails due to some error. + */ + public void messageFlow(String destination, short unit, long value) throws QpidException; + + /** + * Forces the broker to exhaust its credit supply. + *

The broker's credit will always be zero when + * this method completes. This method does not complete until all the message transfers occur. + *

This method returns the number of flushed messages. + * + * @param destination The destination to call flush on. + * @return The number of flushed messages + * @throws QpidException If flushing fails due to some error. + */ + public int messageFlush(String destination) throws QpidException; + + /** + * On receipt of this method, the brokers MUST set his credit to zero for the given + * destination. This obeys the generic semantics of command completion, i.e. when confirmation + * is issued credit MUST be zero and no further messages will be sent until such a time as + * further credit is received. + * + * @param destination The destination to stop. + * @throws QpidException If stopping fails due to some error. + */ + public void messageStop(String destination) throws QpidException; + + /** + * Acknowledge the receipt of ranges of messages. + *

Message must have been previously acquired either by receiving them in + * pre-acquire mode or by explicitly acquiring them. + * + * @param range Range of acknowledged messages. + * @throws QpidException If the acknowledgement of the messages fails due to some error. + */ + public void messageAcknowledge(Range... range) throws QpidException; + + /** + * Reject ranges of acquired messages. + *

A rejected message will not be delivered to any receiver + * and may be either discarded or moved to the broker dead letter queue. + * + * @param range Range of rejected messages. + * @throws QpidException If those messages cannot be rejected dus to some error + */ + public void messageReject(Range... range) throws QpidException; + + /** + * Try to acquire ranges of messages hence releasing them form the queue. + * This means that once acknowledged, a message will not be delivered to any other receiver. + *

As those messages may have been consumed by another receivers hence, + * message acquisition can fail. + * The outcome of the acquisition is returned as an array of ranges of qcquired messages. + *

This method should only be called on non-acquired messages. + * + * @param range Ranges of messages to be acquired. + * @return Ranges of explicitly acquired messages. + * @throws QpidException If this message cannot be acquired dus to some error + */ + public Range[] messageAcquire(Range... range) throws QpidException; + + /** + * Give up responsibility for processing ranges of messages. + *

Released messages are re-enqueued. + * + * @param range Ranges of messages to be released. + * @throws QpidException If this message cannot be released dus to some error. + */ + public void messageRelease(Range... range) throws QpidException; + + // ----------------------------------------------- + // Local transaction methods + // ---------------------------------------------- + /** + * Selects the session for local transaction support. + * + * @throws QpidException If selecting this session for local transaction support fails due to some error. + */ + public void txSelect() throws QpidException; + + /** + * Commit the receipt and the delivery of all messages exchanged by this session resources. + * + * @throws QpidException If the session fails to commit due to some error. + * @throws IllegalStateException If this session is not transacted. + */ + public void txCommit() throws QpidException, IllegalStateException; + + /** + * Rollback the receipt and the delivery of all messages exchanged by this session resources. + * + * @throws QpidException If the session fails to rollback due to some error. + * @throws IllegalStateException If this session is not transacted. + */ + public void txRollback() throws QpidException, IllegalStateException; + + //--------------------------------------------- + // Queue methods + //--------------------------------------------- + + /** + * Declare a queue with the given queueName + *

Following are the valid options for declareQueue + *

    + *
  • AUTO_DELETE + *
  • DURABLE + *
  • EXCLUSIVE + *
  • NO_WAIT + *
  • PASSIVE + *
+ *

+ *

+ *

In the absence of a particular option, the defaul value is false for each option + * + * @param queueName The name of the delcared queue. + * @param alternateExchange If a message is rejected by a queue, then it is sent to the alternate-exchange. A message + * may be rejected by a queue for the following reasons: + *

  1. The queue is deleted when it is not empty; + * <
  2. Immediate delivery of a message is requested, but there are no consumers connected to + * the queue.
+ * @param arguments Used for backward compatibility + * @param options Set of Options. + * @throws QpidException If the session fails to declare the queue due to some error. + * @see Option + */ + public void queueDeclare(String queueName, String alternateExchange, Map arguments, Option... options) + throws QpidException; + + /** + * Bind a queue with an exchange. + * + * @param queueName The queue to be bound. + * @param exchangeName The exchange name. + * @param routingKey The routing key. + * @param arguments Used for backward compatibility + * @throws QpidException If the session fails to bind the queue due to some error. + */ + public void queueBind(String queueName, String exchangeName, String routingKey, Map arguments) + throws QpidException; + + /** + * Unbind a queue from an exchange. + * + * @param queueName The queue to be unbound. + * @param exchangeName The exchange name. + * @param routingKey The routing key. + * @param arguments Used for backward compatibility + * @throws QpidException If the session fails to unbind the queue due to some error. + */ + public void queueUnbind(String queueName, String exchangeName, String routingKey, Map arguments) + throws QpidException; + + /** + * Purge a queue. i.e. delete all enqueued messages + * + * @param queueName The queue to be purged + * @throws QpidException If the session fails to purge the queue due to some error. + */ + public void queuePurge(String queueName) throws QpidException; + + /** + * Delet a queue. + *

Following are the valid options for createReceive + *

    + *
  • IF_EMPTY + *
  • IF_UNUSE + *
  • NO_WAIT + *
+ *

+ *

+ *

In the absence of a particular option, the defaul value is false for each option

+ * + * @param queueName The name of the queue to be deleted + * @param options Set of options + * @throws QpidException If the session fails to delete the queue due to some error. + * @see Option + *

+ * Following are the valid options + */ + public void queueDelete(String queueName, Option... options) throws QpidException; + + // -------------------------------------- + // exhcange methods + // -------------------------------------- + + /** + * Declare an exchange. + *

Following are the valid options for createReceive + *

    + *
  • AUTO_DELETE + *
  • DURABLE + *
  • INTERNAL + *
  • NO_WAIT + *
  • PASSIVE + *
+ *

+ *

+ *

In the absence of a particular option, the defaul value is false for each option

* + * + * @param exchangeName The exchange name. + * @param exchangeClass The fully qualified name of the exchange class. + * @param alternateExchange In the event that a message cannot be routed, this is the name of the exchange to which + * the message will be sent. + * @param options Set of options. + * @param arguments Used for backward compatibility + * @throws QpidException If the session fails to declare the exchange due to some error. + * @see Option + */ + public void exchangeDeclare(String exchangeName, String exchangeClass, String alternateExchange, + Map arguments, Option... options) throws QpidException; + + /** + * Delete an exchange. + *

Following are the valid options for createReceive + *

    + *
  • IF_UNUSEDL + *
  • NO_WAIT + *
+ *

+ *

+ *

In the absence of a particular option, the defaul value is false for each option + * Immediately deleted even if it is used by another resources.

+ * + * @param exchangeName The name of exchange to be deleted. + * @param options Set of options. + * @throws QpidException If the session fails to delete the exchange due to some error. + * @see Option + */ + public void exchangeDelete(String exchangeName, Option... options) throws QpidException; +} -- cgit v1.2.1