View Javadoc

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