001: /*
002: * $Id: OutboundRouter.java 10961 2008-02-22 19:01:02Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api.routing;
012:
013: import org.mule.api.MessagingException;
014: import org.mule.api.MuleMessage;
015: import org.mule.api.MuleSession;
016: import org.mule.api.endpoint.OutboundEndpoint;
017: import org.mule.api.transaction.TransactionConfig;
018:
019: import java.util.List;
020:
021: /**
022: * <code>OutboundRouter</code> is used to control outbound routing behaviour for
023: * an event. One or more Outbound routers can be associated with an
024: * <code>OutboundRouterCollection</code> and will be selected based on the filters
025: * set on the individual Outbound Router.
026: *
027: * @see OutboundRouterCollection
028: */
029:
030: public interface OutboundRouter extends Router {
031: /**
032: * Sets a list of Endpoint instances associated with this router
033: *
034: * @param endpoints a list of Endpoint instances
035: */
036: void setEndpoints(List endpoints);
037:
038: /**
039: * Gets a list of Endpoint instances associated with this router
040: *
041: * @return a list of Endpoint instances
042: */
043: List getEndpoints();
044:
045: /**
046: * Adds an endpoint to this router
047: *
048: * @param endpoint the endpoint to add to the router
049: */
050: void addEndpoint(OutboundEndpoint endpoint);
051:
052: /**
053: * Removes a specific endpoint from the router
054: *
055: * @param endpoint the endpoint to remove
056: * @return true if the endpoint was removed
057: */
058: boolean removeEndpoint(OutboundEndpoint endpoint);
059:
060: /**
061: * This method is responsible for routing the Message via the MuleSession. The logic
062: * for this method will change for each type of router depending on expected
063: * behaviour. For example, a MulticastingRouter might just iterate through the
064: * list of assoaciated endpoints sending the message. Another type of router such
065: * as the ExceptionBasedRouter will hit the first endpoint, if it fails try the
066: * second, and so on. Most router implementations will extends the
067: * FilteringOutboundRouter which implements all the common logic need for a
068: * router.
069: *
070: * @param message the message to send via one or more endpoints on this router
071: * @param session the session used to actually send the event
072: * @param synchronous whether the invocation process should be synchronous or not
073: * @return a result message if any from the invocation. If the synchronous flag
074: * is false a null result will always be returned.
075: * @throws MessagingException if any errors occur during the sending of messages
076: * @see org.mule.routing.outbound.FilteringOutboundRouter
077: * @see org.mule.routing.outbound.ExceptionBasedRouter
078: * @see org.mule.routing.outbound.MulticastingRouter
079: */
080: MuleMessage route(MuleMessage message, MuleSession session,
081: boolean synchronous) throws MessagingException;
082:
083: /**
084: * Determines if the event should be processed by this router. Routers can be
085: * selectively invoked by configuring a filter on them. Usually the filter is
086: * applied to the message when calling this method. All core Mule outbound
087: * routers extend the FilteringOutboundRouter router that handles this method
088: * automatically.
089: *
090: * @param message the current message to evaluate
091: * @return true if the event should be processed by this router
092: * @throws MessagingException if the event cannot be evaluated
093: * @see org.mule.routing.inbound.SelectiveConsumer
094: */
095: boolean isMatch(MuleMessage message) throws MessagingException;
096:
097: TransactionConfig getTransactionConfig();
098:
099: 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: public OutboundEndpoint getEndpoint(String name);
135:
136: }
|