1 /* 2 * $Id: MessageDispatcherFactory.java 12269 2008-07-10 04:19:03Z dfeist $ 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.api.transport; 12 13 import org.mule.api.MuleException; 14 import org.mule.api.endpoint.OutboundEndpoint; 15 16 /** 17 * <code>MessageDispatcherFactory</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 ImmutableEndpoint} as the key and the dispatcher as pooled object. 21 */ 22 public interface MessageDispatcherFactory 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(OutboundEndpoint, MessageDispatcher)} it takes 31 * precedence over the dispatcher's own return value of 32 * {@link MessageDispatcher#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>MessageDispatcher</code> for this 44 * transport 45 * @throws MuleException if the dispatcher cannot be created 46 */ 47 MessageDispatcher create(OutboundEndpoint endpoint) throws MuleException; 48 49 /** 50 * Invoked <strong>before</strong> the given dispatcher is handed out to a 51 * client, but <strong>not</strong> after {@link #create(OutboundEndpoint)}. 52 * 53 * @param endpoint the endpoint of the dispatcher 54 * @param dispatcher the dispatcher to be activated 55 * @throws MuleException if the dispatcher cannot be activated 56 */ 57 void activate(OutboundEndpoint endpoint, MessageDispatcher dispatcher) throws MuleException; 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(OutboundEndpoint, MessageDispatcher)}. 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(OutboundEndpoint endpoint, MessageDispatcher 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(OutboundEndpoint endpoint, MessageDispatcher dispatcher); 79 80 /** 81 * Invoked when a dispatcher returned <code>false</code> for 82 * {@link #validate(OutboundEndpoint, MessageDispatcher)}. 83 * 84 * @param endpoint the endpoint of the dispatcher 85 * @param dispatcher the dispatcher to be validated 86 */ 87 void destroy(OutboundEndpoint endpoint, MessageDispatcher dispatcher); 88 89 }