01: /*
02: * $Id: MessageDispatcherFactory.java 10961 2008-02-22 19:01:02Z dfeist $
03: * --------------------------------------------------------------------------------------
04: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
05: *
06: * The software in this package is published under the terms of the CPAL v1.0
07: * license, a copy of which has been included with this distribution in the
08: * LICENSE.txt file.
09: */
10:
11: package org.mule.api.transport;
12:
13: import org.mule.api.MuleException;
14: import org.mule.api.endpoint.ImmutableEndpoint;
15: import org.mule.api.endpoint.OutboundEndpoint;
16:
17: /**
18: * <code>MessageDispatcherFactory</code> is a factory interface for managing the
19: * lifecycles of a transport's message dispatchers. The methods basically implement
20: * the {@link org.apache.commons.pool.KeyedPoolableObjectFactory} lifecycle, with a
21: * {@link ImmutableEndpoint} as the key and the dispatcher as pooled object.
22: */
23: public interface MessageDispatcherFactory {
24:
25: /**
26: * Controls whether dispatchers are cached or created per request. Note that if
27: * an exception occurs in the dispatcher, it is automatically disposed of and a
28: * new one is created for the next request. This allows dispatchers to recover
29: * from loss of connection and other faults. When invoked by
30: * {@link #validate(OutboundEndpoint, MessageDispatcher)} it takes
31: * precedence over the dispatcher's own return value of
32: * {@link MessageDispatcher#validate()}.
33: *
34: * @return true if created per request
35: */
36: boolean isCreateDispatcherPerRequest();
37:
38: /**
39: * Creates a new message dispatcher instance, initialised with the passed
40: * endpoint. The returned instance should be immediately useable.
41: *
42: * @param endpoint the endoint for which this dispatcher should be created
43: * @return a properly created <code>MessageDispatcher</code> for this
44: * transport
45: * @throws MuleException if the dispatcher cannot be created
46: */
47: MessageDispatcher create(OutboundEndpoint endpoint)
48: throws MuleException;
49:
50: /**
51: * Invoked <strong>before</strong> the given dispatcher is handed out to a
52: * client, but <strong>not</strong> after {@link #create(OutboundEndpoint)}.
53: *
54: * @param endpoint the endpoint of the dispatcher
55: * @param dispatcher the dispatcher to be activated
56: * @throws MuleException if the dispatcher cannot be activated
57: */
58: void activate(OutboundEndpoint endpoint,
59: MessageDispatcher dispatcher) throws MuleException;
60:
61: /**
62: * Invoked <strong>after</strong> the dispatcher is returned from a client but
63: * <strong>before</strong> it is prepared for return to its pool via
64: * {@link #passivate(OutboundEndpoint, MessageDispatcher)}.
65: *
66: * @param endpoint the endpoint of the dispatcher
67: * @param dispatcher the dispatcher to be validated
68: * @return <code>true</code> if the dispatcher is valid for reuse,
69: * <code>false</code> otherwise.
70: */
71: boolean validate(OutboundEndpoint endpoint,
72: MessageDispatcher dispatcher);
73:
74: /**
75: * Invoked immediately <strong>before</strong> the given dispatcher is returned
76: * to its pool.
77: *
78: * @param endpoint the endpoint of the dispatcher
79: * @param dispatcher the dispatcher to be passivated
80: */
81: void passivate(OutboundEndpoint endpoint,
82: MessageDispatcher dispatcher);
83:
84: /**
85: * Invoked when a dispatcher returned <code>false</code> for
86: * {@link #validate(OutboundEndpoint, MessageDispatcher)}.
87: *
88: * @param endpoint the endpoint of the dispatcher
89: * @param dispatcher the dispatcher to be validated
90: */
91: void destroy(OutboundEndpoint endpoint, MessageDispatcher dispatcher);
92:
93: }
|