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