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 }