ServiceMixClient


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.servicemix.client;
18  
19  import java.util.Map  ;
20  
21  import javax.jbi.JBIException;
22  import javax.jbi.component.ComponentContext;
23  import javax.jbi.messaging.DeliveryChannel;
24  import javax.jbi.messaging.ExchangeStatus;
25  import javax.jbi.messaging.Fault;
26  import javax.jbi.messaging.InOnly;
27  import javax.jbi.messaging.InOptionalOut;
28  import javax.jbi.messaging.InOut;
29  import javax.jbi.messaging.MessageExchange;
30  import javax.jbi.messaging.MessageExchangeFactory;
31  import javax.jbi.messaging.MessagingException;
32  import javax.jbi.messaging.RobustInOnly;
33  import javax.xml.namespace.QName  ;
34  
35  import org.apache.servicemix.jbi.resolver.EndpointResolver;
36  
37  /**
38   * Represents a client  API which allows users to programatically send messages into the JBI
39   * container or to receive them using the regular JBI API together with a collection of helper methods making it
40   * easier to interact with the JBI API.
41   *
42   * @version $Revision: 429658 $
43   */
44  public interface ServiceMixClient {
45  
46  
47      // Core JBI methods
48      //-------------------------------------------------------------------------
49  
50      /**
51       * Sends the message exchange to the endpoint.
52       *
53       * @param exchange
54       * @throws MessagingException
55       */
56      void send(MessageExchange exchange) throws MessagingException;
57  
58      /**
59       * Sends an In-Only message
60       * 
61       * @param message
62       */
63      void send(Message message) throws MessagingException;
64      
65      /**
66       * Sends the message exchange to the endpoint, blocking until the send has completed.
67       *
68       * @param exchange
69       * @throws MessagingException
70       * @return true if the exchange has been processed and returned by the
71       *  servicing component, false otherwise.
72       */
73      boolean sendSync(MessageExchange exchange) throws MessagingException;
74  
75      /**
76       * Sends the message exchange to the endpoint, blocking until the send has completed
77       * or the specified timeout has elapsed.
78       *
79       * @param exchange
80       * @param timeout
81       * @throws MessagingException
82       * @return true if the exchange has been processed and returned by the
83       *  servicing component, false otherwise.
84       */
85      boolean sendSync(MessageExchange exchange, long timeout) throws MessagingException;
86  
87      /**
88       * Receives an inbound message exchange, blocking forever until one is available.
89       *
90       * @return the received message exchange
91       * @throws MessagingException
92       */
93      MessageExchange receive() throws MessagingException;
94  
95      /**
96       * Receives an inbound message exchange, blocking until the given timeout period.
97       *
98       * @param timeout the maximum amount of time to wait for a message
99       * @return the received message exchange or null if the timeout occurred.
100      * @throws MessagingException
101      */
102     MessageExchange receive(long timeout) throws MessagingException;
103 
104 
105     /**
106      * Performs a request-response (using an {@link InOut} to the endpoint denoted by the given resolver,
107      * blocking until the response is received and then returning the result.
108      *
109      * @param resolver            the resolver used to resolve and choose the endpoint, which if null is used
110      *                            then the container configured routing rules are used to dispatch the message to the destination
111      * @param exchangeProperties  the properties used for the exchange or null if no properties are required
112      * @param inMessageProperties the properties used for the in message or null if no properties are required
113      * @param content             the body of the message
114      * @throws JBIException if the message could not be dispatched for some reason.
115      */
116     Object   request(EndpointResolver resolver, Map   exchangeProperties, Map   inMessageProperties, Object   content) throws JBIException;
117 
118     /**
119      * Sends a one way message exchange to the endpoint denoted by the given resolver
120      *
121      * @param resolver            the resolver used to resolve and choose the endpoint, which if null is used
122      *                            then the container configured routing rules are used to dispatch the message to the destination
123      * @param exchangeProperties  the properties used for the exchange or null if no properties are required
124      * @param inMessageProperties the properties used for the in message or null if no properties are required
125      * @param content             the body of the message
126      * @throws JBIException if the message could not be dispatched for some reason.
127      */
128     void send(EndpointResolver resolver, Map   exchangeProperties, Map   inMessageProperties, Object   content) throws JBIException;
129 
130     /**
131      * Sends a one way message exchange to the endpoint denoted by the given resolver and blocks until the send is completed.
132      *
133      * @param resolver            the resolver used to resolve and choose the endpoint, which if null is used
134      *                            then the container configured routing rules are used to dispatch the message to the destination
135      * @param exchangeProperties  the properties used for the exchange or null if no properties are required
136      * @param inMessageProperties the properties used for the in message or null if no properties are required
137      * @param content             the body of the message
138      * @return true if the exchange has been processed and returned by the
139      *  servicing component, false otherwise.
140      * @throws JBIException if the message could not be dispatched for some reason.
141      */
142     boolean sendSync(EndpointResolver resolver, Map   exchangeProperties, Map   inMessageProperties, Object   content) throws JBIException;
143 
144 
145     /**
146      * Performs a request-response (using an {@link InOut} to the endpoint denoted by the given resolver,
147      * blocking until the response is received and then returning the result.
148      *
149      * @param inMessageProperties the properties used for the in message or null if no properties are required
150      * @param content             the body of the message
151      * @throws JBIException if the message could not be dispatched for some reason.
152      */
153     Object   request(Map   inMessageProperties, Object   content) throws JBIException;
154 
155     /**
156      * Sends a one way message exchange to the endpoint denoted by the given resolver
157      *
158      * @param inMessageProperties the properties used for the in message or null if no properties are required
159      * @param content             the body of the message
160      * @throws JBIException if the message could not be dispatched for some reason.
161      */
162     void send(Map   inMessageProperties, Object   content) throws JBIException;
163 
164     /**
165      * Sends a one way message exchange to the endpoint denoted by the given resolver and blocks until the send is completed.
166      *
167      * @param inMessageProperties the properties used for the in message or null if no properties are required
168      * @param content             the body of the message
169      * @return true if the exchange has been processed and returned by the
170      *  servicing component, false otherwise.
171      * @throws JBIException if the message could not be dispatched for some reason.
172      */
173     boolean sendSync(Map   inMessageProperties, Object   content) throws JBIException;
174 
175 
176 
177     // Factory methods to make MessageExchange instances
178     //-------------------------------------------------------------------------
179 
180     /**
181      * Creates an {@link InOnly} (one way) message exchange.
182      *
183      * @return the newly created message exchange
184      * @throws MessagingException
185      */
186     InOnly createInOnlyExchange() throws MessagingException;
187 
188     /**
189      * Creates an {@link InOnly} (one way) message exchange with the given resolver.
190      *
191      * @return the newly created message exchange
192      * @throws MessagingException
193      */
194     InOnly createInOnlyExchange(EndpointResolver resolver) throws JBIException;
195 
196     /**
197      * Creates an {@link InOut} (request-reply) message exchange.
198      *
199      * @return the newly created message exchange
200      * @throws MessagingException
201      */
202     InOut createInOutExchange() throws MessagingException;
203 
204     /**
205      * Creates an {@link InOut} (request-reply) message exchange with the given resolver.
206      *
207      * @return the newly created message exchange
208      * @throws MessagingException
209      */
210     InOut createInOutExchange(EndpointResolver resolver) throws JBIException;
211 
212     /**
213      * Creates an {@link InOptionalOut} (optional request-reply) message exchange.
214      *
215      * @return the newly created message exchange
216      * @throws MessagingException
217      */
218     InOptionalOut createInOptionalOutExchange() throws MessagingException;
219 
220     /**
221      * Creates an {@link InOptionalOut} (optional request-reply) message exchange with the given resolver.
222      *
223      * @return the newly created message exchange
224      * @throws MessagingException
225      */
226     InOptionalOut createInOptionalOutExchange(EndpointResolver resolver) throws JBIException;
227 
228     /**
229      * Creates an {@link RobustInOnly} (one way) message exchange.
230      *
231      * @return the newly created message exchange
232      * @throws MessagingException
233      */
234     RobustInOnly createRobustInOnlyExchange() throws MessagingException;
235 
236     /**
237      * Creates an {@link RobustInOnly} (one way) message exchange with the given resolver.
238      *
239      * @return the newly created message exchange
240      * @throws MessagingException
241      */
242     RobustInOnly createRobustInOnlyExchange(EndpointResolver resolver) throws JBIException;
243 
244 
245 
246     // Helper methods to get an endpoint resolver
247     //-------------------------------------------------------------------------
248 
249     /**
250      * Creates an endpoint resolver for the given service name
251      *
252      * @param service
253      * @return the newly created entity resolver
254      */
255     EndpointResolver createResolverForService(QName   service);
256 
257     /**
258      * Creates an endpoint resolver for the given interface name
259      *
260      * @param interfaceName
261      * @return the newly created entity resolver
262      */
263     EndpointResolver createResolverInterface(QName   interfaceName);
264 
265     /**
266      * Creates an endpoint for the given external service name
267      *
268      * @param service
269      * @return the newly created entity resolver
270      */
271     EndpointResolver createResolverForExternalService(QName   service);
272 
273     /**
274      * Creates an endpoint for the given external interface
275      *
276      * @param interfaceName
277      * @return the newly created entity resolver
278      */
279     EndpointResolver createResolverForExternalInterface(QName   interfaceName);
280 
281     /**
282      * Creates an endpoint resolver for the given service and endpoint name
283      *
284      * @param service
285      * @param endpoint
286      * @return the newly created entity resolver
287      */
288     EndpointResolver createResolverForExternalInterface(QName   service, String   endpoint);
289 
290 
291     // Create a destination
292     //-------------------------------------------------------------------------
293     
294     /**
295      * Creates a destination which represents some JBI endpoint that message exchanges can be created with.
296      * @throws MessagingException 
297      */
298     Destination createDestination(String   uri) throws MessagingException;
299     
300 
301     // Helper methods and access to the JBI context information
302     //-------------------------------------------------------------------------
303 
304 
305     /**
306      * A helper method to indicate that the message exchange is complete
307      * which will set the status to {@link ExchangeStatus#DONE} and send the message
308      * on the delivery channel.
309      *
310      * @param exchange
311      * @throws MessagingException
312      */
313     void done(MessageExchange exchange) throws MessagingException;
314 
315     /**
316      * A helper method which fails and completes the given exchange with the specified fault
317      */
318     void fail(MessageExchange exchange, Fault fault) throws MessagingException;
319 
320     /**
321      * A helper method which fails and completes the given exchange with the specified exception
322      */
323     void fail(MessageExchange exchange, Exception   error) throws MessagingException;
324 
325         
326         /**
327      * Returns the current component context which can be used to activate endpoints, components and
328      * query the available service endpoints.
329      *
330      * @return the component context
331      */
332     ComponentContext getContext();
333 
334     /**
335      * Returns the delivery channel for this client's message exchanges
336      *
337      * @return the delivery channel on which all this clients exchanges will occur.
338      * @throws MessagingException
339      */
340     DeliveryChannel getDeliveryChannel() throws MessagingException;
341 
342     /**
343      * Returns the default message exchange factory.
344      *
345      * @return the default message exchange factory.
346      * @throws MessagingException
347      */
348     MessageExchangeFactory getExchangeFactory() throws MessagingException;
349 
350 
351     /**
352      * Close this client.
353      * 
354      * @throws JBIException
355      */
356     void close() throws JBIException;
357 }
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags