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