01: /*
02: * $Id: MessageRequesterFactory.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.InboundEndpoint;
15:
16: /**
17: * A factory interface for managing the lifecycles of a transport's message requesters.
18: * The methods basically implement
19: * the {@link org.apache.commons.pool.KeyedPoolableObjectFactory} lifecycle, with a
20: * {@link org.mule.api.endpoint.InboundEndpoint} as the key and the requester as pooled object.
21: */
22: public interface MessageRequesterFactory {
23:
24: /**
25: * Controls whether dispatchers are cached or created per request. Note that if
26: * an exception occurs in the requester, it is automatically disposed of and a
27: * new one is created for the next request. This allows requesters to recover
28: * from loss of connection and other faults. When invoked by
29: * {@link #validate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)} it takes
30: * precedence over the dispatcher's own return value of
31: * {@link org.mule.api.transport.MessageDispatcher#validate()}.
32: *
33: * @return true if created per request
34: */
35: boolean isCreateRequesterPerRequest();
36:
37: /**
38: * Creates a new message requester instance, initialised with the passed
39: * endpoint. The returned instance should be immediately useable.
40: *
41: * @param endpoint the endoint for which this requester should be created
42: * @return a properly created <code>UMOMessagerequester</code> for this
43: * transport
44: * @throws org.mule.api.MuleException if the requester cannot be created
45: */
46: MessageRequester create(InboundEndpoint endpoint)
47: throws MuleException;
48:
49: /**
50: * Invoked <strong>before</strong> the given requester is handed out to a
51: * client, but <strong>not</strong> after {@link #create(org.mule.api.endpoint.InboundEndpoint)}.
52: *
53: * @param endpoint the endpoint of the requester
54: * @param requester the requester to be activated
55: * @throws org.mule.api.MuleException if the requester cannot be activated
56: */
57: void activate(InboundEndpoint endpoint, MessageRequester requester)
58: throws MuleException;
59:
60: /**
61: * Invoked <strong>after</strong> the requester is returned from a client but
62: * <strong>before</strong> it is prepared for return to its pool via
63: * {@link #passivate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)}.
64: *
65: * @param endpoint the endpoint of the requester
66: * @param requester the requester to be validated
67: * @return <code>true</code> if the requester is valid for reuse,
68: * <code>false</code> otherwise.
69: */
70: boolean validate(InboundEndpoint endpoint,
71: MessageRequester requester);
72:
73: /**
74: * Invoked immediately <strong>before</strong> the given requester is returned
75: * to its pool.
76: *
77: * @param endpoint the endpoint of the requester
78: * @param requester the requester to be passivated
79: */
80: void passivate(InboundEndpoint endpoint, MessageRequester requester);
81:
82: /**
83: * Invoked when a requester returned <code>false</code> for
84: * {@link #validate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)}.
85: *
86: * @param endpoint the endpoint of the requester
87: * @param requester the requester to be validated
88: */
89: void destroy(InboundEndpoint endpoint, MessageRequester requester);
90:
91: }
|