View Javadoc
1   /*
2    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
3    * The software in this package is published under the terms of the CPAL v1.0
4    * license, a copy of which has been included with this distribution in the
5    * LICENSE.txt file.
6    */
7   package org.mule.api.client;
8   
9   import org.mule.MessageExchangePattern;
10  import org.mule.api.MuleException;
11  import org.mule.api.MuleMessage;
12  
13  import java.util.Map;
14  
15  /**
16   * Provides methods for performing send, dispatch and request operations
17   * programatically.
18   */
19  public interface MuleClient
20  {
21  
22      /**
23       * Dispatches an event asynchronously to a endpointUri via a Mule server. The URL
24       * determines where to dispatch the event to.
25       * 
26       * @param url the Mule URL used to determine the destination and transport of the
27       *            message
28       * @param payload the object that is the payload of the event
29       * @param messageProperties any properties to be associated with the payload. In
30       *            the case of JMS you could set the JMSReplyTo property in these
31       *            properties.
32       * @throws org.mule.api.MuleException
33       */
34      void dispatch(String url, Object payload, Map<String, Object> messageProperties) throws MuleException;
35  
36      /**
37       * Dispatches an event asynchronously to a endpointUri via a Mule server. The URL
38       * determines where to dispatch the event to.
39       * 
40       * @param url the Mule URL used to determine the destination and transport of the
41       *            message
42       * @param message the message to send
43       * @throws org.mule.api.MuleException
44       */
45      void dispatch(String url, MuleMessage message) throws MuleException;
46  
47      /**
48       * Sends an event synchronously to a endpointUri via a Mule server and a
49       * resulting message is returned.
50       * 
51       * @param url the Mule URL used to determine the destination and transport of the
52       *            message
53       * @param payload the object that is the payload of the event
54       * @param messageProperties any properties to be associated with the payload. In
55       *            the case of Jms you could set the JMSReplyTo property in these
56       *            properties.
57       * @return A return message, this could be <code>null</code> if the the
58       *         components invoked explicitly sets a return as <code>null</code>.
59       * @throws org.mule.api.MuleException
60       */
61      MuleMessage send(String url, Object payload, Map<String, Object> messageProperties) throws MuleException;
62  
63      /**
64       * Sends an event synchronously to a endpointUri via a Mule server and a
65       * resulting message is returned.
66       * 
67       * @param url the Mule URL used to determine the destination and transport of the
68       *            message
69       * @param message the Message for the event
70       * @return A return message, this could be <code>null</code> if the the
71       *         components invoked explicitly sets a return as <code>null</code>.
72       * @throws org.mule.api.MuleException
73       */
74      MuleMessage send(String url, MuleMessage message) throws MuleException;
75  
76      /**
77       * Sends an event synchronously to a endpointUri via a mule server and a
78       * resulting message is returned.
79       * 
80       * @param url the Mule URL used to determine the destination and transport of the
81       *            message
82       * @param payload the object that is the payload of the event
83       * @param messageProperties any properties to be associated with the payload. In
84       *            the case of Jms you could set the JMSReplyTo property in these
85       *            properties.
86       * @param timeout The time in milliseconds the the call should block waiting for
87       *            a response
88       * @return A return message, this could be <code>null</code> if the the
89       *         components invoked explicitly sets a return as <code>null</code>.
90       * @throws org.mule.api.MuleException
91       */
92      MuleMessage send(String url, Object payload, Map<String, Object> messageProperties, long timeout)
93          throws MuleException;
94  
95      /**
96       * Sends an event synchronously to a endpointUri via a mule server and a
97       * resulting message is returned.
98       * 
99       * @param url the Mule URL used to determine the destination and transport of the
100      *            message
101      * @param message The message to send
102      * @param timeout The time in milliseconds the the call should block waiting for
103      *            a response
104      * @return A return message, this could be <code>null</code> if the the
105      *         components invoked explicitly sets a return as <code>null</code>.
106      * @throws org.mule.api.MuleException
107      */
108     MuleMessage send(String url, MuleMessage message, long timeout) throws MuleException;
109 
110     /**
111      * Will receive an event from an endpointUri determined by the URL.
112      * 
113      * @param url the Mule URL used to determine the destination and transport of the
114      *            message
115      * @param timeout how long to block waiting to receive the event, if set to 0 the
116      *            receive will not wait at all and if set to -1 the receive will wait
117      *            forever
118      * @return the message received or <code>null</code> if no message was received
119      * @throws org.mule.api.MuleException
120      */
121     MuleMessage request(String url, long timeout) throws MuleException;
122 
123     /**
124      * Will register the specified process as a listener for the inbound endpoint.
125      * This may be implemented by subscription or polling depending on the transport
126      * implementation
127      * 
128      * @param url endpoint uri
129      * @param processor the processor to register
130      * @param frequency the polling frequency (if transport polls)
131      * @throws MuleException
132      */
133     // void receive(String url, MessageProcessor processor, long frequency) throws
134     // MuleException;
135 
136     /**
137      * Processes a message with an outbound endpoint using the specified
138      * {@link MessageExchangePattern}
139      * 
140      * @param uri
141      * @param mep the {@link MessageExchangePattern} that should be used
142      * @param payload the message payload
143      * @param messageProperties and message properties that should be used (optional,
144      *            use null otherwise)
145      * @return the result of endpoint invocation if the
146      *         {@link MessageExchangePattern} defines a response else null.
147      * @throws MuleException
148      */
149     MuleMessage process(String uri,
150                         MessageExchangePattern mep,
151                         Object payload,
152                         Map<String, Object> messageProperties) throws MuleException;
153 
154     /**
155      * Processes a messsage with an outbound endpoint using the specified
156      * {@link MessageExchangePattern}
157      * 
158      * @param uri
159      * @param mep the {@link MessageExchangePattern} that should be used
160      * @param message the message to be processed
161      * @return the result of endpoint invocation if the
162      *         {@link MessageExchangePattern} defines a response else null.
163      * @throws MuleException
164      */
165     MuleMessage process(String uri, MessageExchangePattern mep, MuleMessage message) throws MuleException;
166 
167 }