View Javadoc

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