View Javadoc

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