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 }