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