View Javadoc

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