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