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    }