001 /*
002 * Copyright 2009 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License. You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied. See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014 package org.hornetq.api.core.client;
015
016 import org.hornetq.api.core.HornetQException;
017 import org.hornetq.api.core.Message;
018 import org.hornetq.api.core.SimpleString;
019
020 /**
021 * A ClientProducer is used to send messages to a specific address. Messages are then routed on the server to any queues
022 * that are bound to the address. A ClientProducer can either be created with a specific address in mind or with none.
023 * With the latter the address must be provided using the appropriate send() method. <br><br>
024 *
025 * The sending semantics can change depending on what blocking semantics are set via {@link ClientSessionFactory#setBlockOnDurableSend(boolean)}
026 * and {@link org.hornetq.api.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)} . If set to true
027 * then for each message type, durable and non durable respectively, any exceptions such as the address not existing or
028 * security exceptions will be thrown at the time of send. Alternatively if set to false then exceptions will only be
029 * logged on the server. <br><br>
030 *
031 * The send rate can also be controlled via {@link ClientSessionFactory#setProducerMaxRate(int)}
032 * and the {@link org.hornetq.api.core.client.ClientSessionFactory#setProducerWindowSize(int)}. <br><br>
033 *
034 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
035 * @author <a href="mailto:ataylor@redhat.com">Andy Taylor</a>
036 */
037 public interface ClientProducer
038 {
039 /**
040 * Returns the address where messages will be sent.
041 *
042 * <br><br>The address can be <code>null</code> if the ClientProducer
043 *
044 * was creating without specifying an address, that is by using {@link ClientSession#createProducer()}.
045 *
046 * @return the address where messages will be sent
047 */
048 SimpleString getAddress();
049
050 /**
051 * Sends a message to an address.
052 *
053 * specified in {@link ClientSession#createProducer(String)} or similar methods.
054 *
055 * <br><br>This will block until confirmation that the message has reached the server has been received if
056 * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.api.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
057 * are set to <code>true</code> for the specified message type.
058 *
059 * @param message the message to send
060 * @throws HornetQException if an exception occurs while sending the message
061 */
062 void send(Message message) throws HornetQException;
063
064 /**
065 * Sends a message to the specified address instead of the ClientProducer's address.
066 *
067 * <br><br>This will block until confirmation that the message has reached the server has been received if
068 * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.api.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
069 * are set to true for the specified message type.
070 *
071 * @param address the address where the message will be sent
072 * @param message the message to send
073 * @throws HornetQException if an exception occurs while sending the message
074 */
075 void send(SimpleString address, Message message) throws HornetQException;
076
077 /**
078 * Sends a message to the specified address instead of the ClientProducer's address.
079 *
080 * <br><br>This will block until confirmation that the message has reached the server has been received if
081 * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.api.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
082 * are set to true for the specified message type.
083 *
084 * @param address the address where the message will be sent
085 * @param message the message to send
086 * @throws HornetQException if an exception occurs while sending the message
087 */
088 void send(String address, Message message) throws HornetQException;
089
090 /**
091 * Closes the ClientProducer. If already closed nothing is done.
092 *
093 * @throws HornetQException if an exception occurs while closing the producer
094 */
095 void close() throws HornetQException;
096
097 /**
098 * Returns whether the producer is closed or not.
099 *
100 * @return <code>true</code> if the producer is closed, <code>false</code> else
101 */
102 boolean isClosed();
103
104 /**
105 * Returns whether the producer will block when sending <em>durable</em> messages.
106 *
107 * @return <code>true</code> if the producer blocks when sending durable, <code>false</code> else
108 */
109 boolean isBlockOnDurableSend();
110
111 /**
112 * Returns whether the producer will block when sending <em>non-durable</em> messages.
113 *
114 * @return <code>true</code> if the producer blocks when sending non-durable, <code>false</code> else
115 */
116 boolean isBlockOnNonDurableSend();
117
118 /**
119 * Returns the maximum rate at which a ClientProducer can send messages per second.
120 *
121 * @return the producers maximum rate
122 */
123 int getMaxRate();
124 }