View Javadoc

1   /*
2    * $Id: OutboundRouter.java 12269 2008-07-10 04:19:03Z dfeist $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSource, Inc.  All rights reserved.  http://www.mulesource.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.routing;
12  
13  import org.mule.api.MessagingException;
14  import org.mule.api.MuleMessage;
15  import org.mule.api.MuleSession;
16  import org.mule.api.endpoint.OutboundEndpoint;
17  import org.mule.api.transaction.TransactionConfig;
18  
19  import java.util.List;
20  
21  /**
22   * <code>OutboundRouter</code> is used to control outbound routing behaviour for
23   * an event. One or more Outbound routers can be associated with an
24   * <code>OutboundRouterCollection</code> and will be selected based on the filters
25   * set on the individual Outbound Router.
26   * 
27   * @see OutboundRouterCollection
28   */
29  
30  public interface OutboundRouter extends Router
31  {
32      /**
33       * Sets a list of Endpoint instances associated with this router
34       * 
35       * @param endpoints a list of Endpoint instances
36       */
37      void setEndpoints(List endpoints);
38  
39      /**
40       * Gets a list of Endpoint instances associated with this router
41       * 
42       * @return a list of Endpoint instances
43       */
44      List getEndpoints();
45  
46      /**
47       * Adds an endpoint to this router
48       * 
49       * @param endpoint the endpoint to add to the router
50       */
51      void addEndpoint(OutboundEndpoint endpoint);
52  
53      /**
54       * Removes a specific endpoint from the router
55       * 
56       * @param endpoint the endpoint to remove
57       * @return true if the endpoint was removed
58       */
59      boolean removeEndpoint(OutboundEndpoint endpoint);
60  
61      /**
62       * This method is responsible for routing the Message via the MuleSession. The logic
63       * for this method will change for each type of router depending on expected
64       * behaviour. For example, a MulticastingRouter might just iterate through the
65       * list of assoaciated endpoints sending the message. Another type of router such
66       * as the ExceptionBasedRouter will hit the first endpoint, if it fails try the
67       * second, and so on. Most router implementations will extends the
68       * FilteringOutboundRouter which implements all the common logic need for a
69       * router.
70       * 
71       * @param message the message to send via one or more endpoints on this router
72       * @param session the session used to actually send the event
73       * @param synchronous whether the invocation process should be synchronous or not
74       * @return a result message if any from the invocation. If the synchronous flag
75       *         is false a null result will always be returned.
76       * @throws MessagingException if any errors occur during the sending of messages
77       * @see org.mule.routing.outbound.FilteringOutboundRouter
78       * @see org.mule.routing.outbound.ExceptionBasedRouter
79       * @see org.mule.routing.outbound.MulticastingRouter
80       */
81      MuleMessage route(MuleMessage message, MuleSession session, boolean synchronous) throws MessagingException;
82  
83      /**
84       * Determines if the event should be processed by this router. Routers can be
85       * selectively invoked by configuring a filter on them. Usually the filter is
86       * applied to the message when calling this method. All core Mule outbound
87       * routers extend the FilteringOutboundRouter router that handles this method
88       * automatically.
89       * 
90       * @param message the current message to evaluate
91       * @return true if the event should be processed by this router
92       * @throws MessagingException if the event cannot be evaluated
93       * @see org.mule.routing.inbound.SelectiveConsumer
94       */
95      boolean isMatch(MuleMessage message) throws MessagingException;
96  
97      TransactionConfig getTransactionConfig();
98  
99      void setTransactionConfig(TransactionConfig transactionConfig);
100 
101     /**
102      * Gets the replyTo endpoint for any outgoing messages. This will then be used by
103      * other Mule routers to send replies back for this message. If the underlying
104      * protocol supports replyTo messages, such as Jms, a Jms Destination will be
105      * attached to the outbound message
106      * 
107      * @return the replyTo endpoint or null if one has not been set.
108      */
109     String getReplyTo();
110 
111     /**
112      * Sets the replyTo endpoint for any outgoing messages. This will then be used by
113      * other Mule routers to send replies back for this message. If the underlying
114      * protocol supports replyTo messages, such as Jms, a Jms Destination will be
115      * attached to the outbound message
116      * 
117      * @param replyTo endpoint string to use
118      */
119     void setReplyTo(String replyTo);
120 
121     /**
122      * Determines whether this router supports dynamic endpoint. i.e. endpoints that
123      * are not configured at design time. Endpoints might be pulled from the message
124      * or payload.
125      * 
126      * @return
127      */
128     boolean isDynamicEndpoints();
129 
130     /**
131      * @param name the Endpoint identifier
132      * @return the Endpoint or null if the endpointUri is not registered
133      */
134     OutboundEndpoint getEndpoint(String name);
135 
136 }