001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.servicemix.client;
018:
019: import java.util.Map;
020:
021: import javax.jbi.JBIException;
022: import javax.jbi.component.ComponentContext;
023: import javax.jbi.messaging.DeliveryChannel;
024: import javax.jbi.messaging.Fault;
025: import javax.jbi.messaging.InOnly;
026: import javax.jbi.messaging.InOptionalOut;
027: import javax.jbi.messaging.InOut;
028: import javax.jbi.messaging.MessageExchange;
029: import javax.jbi.messaging.MessageExchangeFactory;
030: import javax.jbi.messaging.MessagingException;
031: import javax.jbi.messaging.RobustInOnly;
032: import javax.jbi.servicedesc.ServiceEndpoint;
033: import javax.xml.namespace.QName;
034:
035: import org.apache.servicemix.jbi.resolver.EndpointResolver;
036:
037: /**
038: * Represents a client API which allows users to programatically send messages into the JBI
039: * container or to receive them using the regular JBI API together with a collection of helper methods making it
040: * easier to interact with the JBI API.
041: *
042: * @version $Revision: 564374 $
043: */
044: public interface ServiceMixClient {
045:
046: // Core JBI methods
047: //-------------------------------------------------------------------------
048:
049: /**
050: * Sends the message exchange to the endpoint.
051: *
052: * @param exchange
053: * @throws MessagingException
054: */
055: void send(MessageExchange exchange) throws MessagingException;
056:
057: /**
058: * Sends an In-Only message
059: *
060: * @param message
061: */
062: void send(Message message) throws MessagingException;
063:
064: /**
065: * Sends the message exchange to the endpoint, blocking until the send has completed.
066: *
067: * @param exchange
068: * @throws MessagingException
069: * @return true if the exchange has been processed and returned by the
070: * servicing component, false otherwise.
071: */
072: boolean sendSync(MessageExchange exchange)
073: throws MessagingException;
074:
075: /**
076: * Sends the message exchange to the endpoint, blocking until the send has completed
077: * or the specified timeout has elapsed.
078: *
079: * @param exchange
080: * @param timeout
081: * @throws MessagingException
082: * @return true if the exchange has been processed and returned by the
083: * servicing component, false otherwise.
084: */
085: boolean sendSync(MessageExchange exchange, long timeout)
086: throws MessagingException;
087:
088: /**
089: * Receives an inbound message exchange, blocking forever until one is available.
090: *
091: * @return the received message exchange
092: * @throws MessagingException
093: */
094: MessageExchange receive() throws MessagingException;
095:
096: /**
097: * Receives an inbound message exchange, blocking until the given timeout period.
098: *
099: * @param timeout the maximum amount of time to wait for a message
100: * @return the received message exchange or null if the timeout occurred.
101: * @throws MessagingException
102: */
103: MessageExchange receive(long timeout) throws MessagingException;
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,
117: Map inMessageProperties, Object content)
118: throws JBIException;
119:
120: /**
121: * Sends a one way message exchange to the endpoint denoted by the given resolver
122: *
123: * @param resolver the resolver used to resolve and choose the endpoint, which if null is used
124: * then the container configured routing rules are used to dispatch the message to the destination
125: * @param exchangeProperties the properties used for the exchange or null if no properties are required
126: * @param inMessageProperties the properties used for the in message or null if no properties are required
127: * @param content the body of the message
128: * @throws JBIException if the message could not be dispatched for some reason.
129: */
130: void send(EndpointResolver resolver, Map exchangeProperties,
131: Map inMessageProperties, Object content)
132: throws JBIException;
133:
134: /**
135: * Sends a one way message exchange to the endpoint denoted by the given resolver and blocks until the send is completed.
136: *
137: * @param resolver the resolver used to resolve and choose the endpoint, which if null is used
138: * then the container configured routing rules are used to dispatch the message to the destination
139: * @param exchangeProperties the properties used for the exchange or null if no properties are required
140: * @param inMessageProperties the properties used for the in message or null if no properties are required
141: * @param content the body of the message
142: * @return true if the exchange has been processed and returned by the
143: * servicing component, false otherwise.
144: * @throws JBIException if the message could not be dispatched for some reason.
145: */
146: boolean sendSync(EndpointResolver resolver, Map exchangeProperties,
147: Map inMessageProperties, Object content)
148: throws JBIException;
149:
150: /**
151: * Performs a request-response (using an {@link InOut} to the endpoint denoted by the given resolver,
152: * blocking until the response is received and then returning the result.
153: *
154: * @param inMessageProperties the properties used for the in message or null if no properties are required
155: * @param content the body of the message
156: * @throws JBIException if the message could not be dispatched for some reason.
157: */
158: Object request(Map inMessageProperties, Object content)
159: throws JBIException;
160:
161: /**
162: * Sends a one way message exchange to the endpoint denoted by the given resolver
163: *
164: * @param inMessageProperties the properties used for the in message or null if no properties are required
165: * @param content the body of the message
166: * @throws JBIException if the message could not be dispatched for some reason.
167: */
168: void send(Map inMessageProperties, Object content)
169: throws JBIException;
170:
171: /**
172: * Sends a one way message exchange to the endpoint denoted by the given resolver and blocks until the send is completed.
173: *
174: * @param inMessageProperties the properties used for the in message or null if no properties are required
175: * @param content the body of the message
176: * @return true if the exchange has been processed and returned by the
177: * servicing component, false otherwise.
178: * @throws JBIException if the message could not be dispatched for some reason.
179: */
180: boolean sendSync(Map inMessageProperties, Object content)
181: throws JBIException;
182:
183: // Factory methods to make MessageExchange instances
184: //-------------------------------------------------------------------------
185:
186: /**
187: * Creates an {@link InOnly} (one way) message exchange.
188: *
189: * @return the newly created message exchange
190: * @throws MessagingException
191: */
192: InOnly createInOnlyExchange() throws MessagingException;
193:
194: /**
195: * Creates an {@link InOnly} (one way) message exchange with the given resolver.
196: *
197: * @return the newly created message exchange
198: * @throws MessagingException
199: */
200: InOnly createInOnlyExchange(EndpointResolver resolver)
201: throws JBIException;
202:
203: /**
204: * Creates an {@link InOut} (request-reply) message exchange.
205: *
206: * @return the newly created message exchange
207: * @throws MessagingException
208: */
209: InOut createInOutExchange() throws MessagingException;
210:
211: /**
212: * Creates an {@link InOut} (request-reply) message exchange with the given resolver.
213: *
214: * @return the newly created message exchange
215: * @throws MessagingException
216: */
217: InOut createInOutExchange(EndpointResolver resolver)
218: throws JBIException;
219:
220: /**
221: * Creates an {@link InOptionalOut} (optional request-reply) message exchange.
222: *
223: * @return the newly created message exchange
224: * @throws MessagingException
225: */
226: InOptionalOut createInOptionalOutExchange()
227: throws MessagingException;
228:
229: /**
230: * Creates an {@link InOptionalOut} (optional request-reply) message exchange with the given resolver.
231: *
232: * @return the newly created message exchange
233: * @throws MessagingException
234: */
235: InOptionalOut createInOptionalOutExchange(EndpointResolver resolver)
236: throws JBIException;
237:
238: /**
239: * Creates an {@link RobustInOnly} (one way) message exchange.
240: *
241: * @return the newly created message exchange
242: * @throws MessagingException
243: */
244: RobustInOnly createRobustInOnlyExchange() throws MessagingException;
245:
246: /**
247: * Creates an {@link RobustInOnly} (one way) message exchange with the given resolver.
248: *
249: * @return the newly created message exchange
250: * @throws MessagingException
251: */
252: RobustInOnly createRobustInOnlyExchange(EndpointResolver resolver)
253: throws JBIException;
254:
255: /**
256: * Resolves a WS-Addressing endpoint reference String into a JBI {@link javax.jbi.servicedesc.ServiceEndpoint}
257: * reference so that message exchanges can be directed to an endpoint
258: *
259: * @param uri the WS-Addressing endpoint reference string
260: */
261: ServiceEndpoint resolveEndpointReference(String uri);
262:
263: // Helper methods to get an endpoint resolver
264: //-------------------------------------------------------------------------
265:
266: /**
267: * Creates an endpoint resolver for the given service name
268: *
269: * @param service
270: * @return the newly created entity resolver
271: */
272: EndpointResolver createResolverForService(QName service);
273:
274: /**
275: * Creates an endpoint resolver for the given interface name
276: *
277: * @param interfaceName
278: * @return the newly created entity resolver
279: */
280: EndpointResolver createResolverInterface(QName interfaceName);
281:
282: /**
283: * Creates an endpoint for the given external service name
284: *
285: * @param service
286: * @return the newly created entity resolver
287: */
288: EndpointResolver createResolverForExternalService(QName service);
289:
290: /**
291: * Creates an endpoint for the given external interface
292: *
293: * @param interfaceName
294: * @return the newly created entity resolver
295: */
296: EndpointResolver createResolverForExternalInterface(
297: QName interfaceName);
298:
299: /**
300: * Creates an endpoint resolver for the given service and endpoint name
301: *
302: * @param service
303: * @param endpoint
304: * @return the newly created entity resolver
305: */
306: EndpointResolver createResolverForExternalInterface(QName service,
307: String endpoint);
308:
309: // Create a destination
310: //-------------------------------------------------------------------------
311:
312: /**
313: * Creates a destination which represents some JBI endpoint that message exchanges can be created with.
314: * @throws MessagingException
315: */
316: Destination createDestination(String uri) throws MessagingException;
317:
318: // Helper methods and access to the JBI context information
319: //-------------------------------------------------------------------------
320:
321: /**
322: * A helper method to indicate that the message exchange is complete
323: * which will set the status to {@link ExchangeStatus#DONE} and send the message
324: * on the delivery channel.
325: *
326: * @param exchange
327: * @throws MessagingException
328: */
329: void done(MessageExchange exchange) throws MessagingException;
330:
331: /**
332: * A helper method which fails and completes the given exchange with the specified fault
333: */
334: void fail(MessageExchange exchange, Fault fault)
335: throws MessagingException;
336:
337: /**
338: * A helper method which fails and completes the given exchange with the specified exception
339: */
340: void fail(MessageExchange exchange, Exception error)
341: throws MessagingException;
342:
343: /**
344: * Returns the current component context which can be used to activate endpoints, components and
345: * query the available service endpoints.
346: *
347: * @return the component context
348: */
349: ComponentContext getContext();
350:
351: /**
352: * Returns the delivery channel for this client's message exchanges
353: *
354: * @return the delivery channel on which all this clients exchanges will occur.
355: * @throws MessagingException
356: */
357: DeliveryChannel getDeliveryChannel() throws MessagingException;
358:
359: /**
360: * Returns the default message exchange factory.
361: *
362: * @return the default message exchange factory.
363: * @throws MessagingException
364: */
365: MessageExchangeFactory getExchangeFactory()
366: throws MessagingException;
367:
368: /**
369: * Close this client.
370: *
371: * @throws JBIException
372: */
373: void close() throws JBIException;
374:
375: }
|