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 }