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
014package org.hornetq.api.core.client;
015
016import org.hornetq.api.core.HornetQException;
017import org.hornetq.api.core.Message;
018import 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 */
037public 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}