View Javadoc

1   /*
2    * $Id: MessageRequesterFactory.java 10961 2008-02-22 19:01:02Z 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.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      /**
26       * Controls whether dispatchers are cached or created per request. Note that if
27       * an exception occurs in the requester, it is automatically disposed of and a
28       * new one is created for the next request. This allows requesters to recover
29       * from loss of connection and other faults. When invoked by
30       * {@link #validate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)} it takes
31       * precedence over the dispatcher's own return value of
32       * {@link org.mule.api.transport.MessageDispatcher#validate()}.
33       *
34       * @return true if created per request
35       */
36      boolean isCreateRequesterPerRequest();
37  
38      /**
39       * Creates a new message requester instance, initialised with the passed
40       * endpoint. The returned instance should be immediately useable.
41       *
42       * @param endpoint the endoint for which this requester should be created
43       * @return a properly created <code>UMOMessagerequester</code> for this
44       *         transport
45       * @throws org.mule.api.MuleException if the requester cannot be created
46       */
47      MessageRequester create(InboundEndpoint endpoint) 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) throws MuleException;
58  
59      /**
60       * Invoked <strong>after</strong> the requester is returned from a client but
61       * <strong>before</strong> it is prepared for return to its pool via
62       * {@link #passivate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)}.
63       *
64       * @param endpoint the endpoint of the requester
65       * @param requester the requester to be validated
66       * @return <code>true</code> if the requester is valid for reuse,
67       *         <code>false</code> otherwise.
68       */
69      boolean validate(InboundEndpoint endpoint, MessageRequester requester);
70  
71      /**
72       * Invoked immediately <strong>before</strong> the given requester is returned
73       * to its pool.
74       *
75       * @param endpoint the endpoint of the requester
76       * @param requester the requester to be passivated
77       */
78      void passivate(InboundEndpoint endpoint, MessageRequester requester);
79  
80      /**
81       * Invoked when a requester returned <code>false</code> for
82       * {@link #validate(org.mule.api.endpoint.InboundEndpoint, org.mule.api.transport.MessageRequester)}.
83       *
84       * @param endpoint the endpoint of the requester
85       * @param requester the requester to be validated
86       */
87      void destroy(InboundEndpoint endpoint, MessageRequester requester);
88  
89  }