1 /* 2 * $Id: Connector.java 19704 2010-09-22 19:26:15Z 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.MessageExchangePattern; 14 import org.mule.api.MuleContext; 15 import org.mule.api.MuleEvent; 16 import org.mule.api.MuleException; 17 import org.mule.api.MuleMessage; 18 import org.mule.api.NamedObject; 19 import org.mule.api.construct.FlowConstruct; 20 import org.mule.api.endpoint.InboundEndpoint; 21 import org.mule.api.endpoint.OutboundEndpoint; 22 import org.mule.api.lifecycle.CreateException; 23 import org.mule.api.lifecycle.Lifecycle; 24 import org.mule.api.lifecycle.LifecycleStateEnabled; 25 import org.mule.api.processor.MessageProcessor; 26 import org.mule.api.retry.RetryPolicyTemplate; 27 28 import java.io.OutputStream; 29 import java.util.List; 30 31 /** 32 * <code>Connector</code> is the mechanism used to connect to external systems 33 * and protocols in order to send and receive data. 34 */ 35 public interface Connector extends Lifecycle, NamedObject, Connectable, LifecycleStateEnabled 36 { 37 int INT_VALUE_NOT_SET = -1; 38 39 /** 40 * Registers a MessageProcessor listener which will listen to new message 41 * received from a specific transport channel and then processed by the endpoint. 42 * Only a single listener can be registered for a given endpoints. Attempts to 43 * register a listener when one is already registered will fail. 44 * 45 * @param endpoint defines both the transport and channel/resource uri as well 46 * the processing (transformation/filtering) that should occur when 47 * the endpoint processes a new message from the transport receiver. 48 * @param listener the listener that will be invoked when messages are received 49 * on the endpoint. 50 * @param pattern reference to the runtime construct that the listener is part of 51 * for use as context for logging, notifications and error handling. 52 * @throws Exception 53 */ 54 public void registerListener(InboundEndpoint endpoint, MessageProcessor listener, FlowConstruct flowConstruct) 55 throws Exception; 56 57 /** 58 * Unregisters the listener for the given endpoints. This will mean that the 59 * listener that was registered for this endpoint will no longer receive any 60 * messages. 61 * 62 * @param endpoint 63 * @throws Exception 64 */ 65 public void unregisterListener(InboundEndpoint endpoint, FlowConstruct flowConstruct) throws Exception; 66 67 /** 68 * @return true if the endpoint is started 69 */ 70 boolean isStarted(); 71 72 boolean isConnected(); 73 74 /** 75 * @return false if the connector is alive and well or true if the connector is 76 * being destroyed 77 */ 78 boolean isDisposed(); 79 80 /** 81 * Creates a new {@link MuleMessageFactory} using what's defined in the connector's 82 * transport service descriptor. 83 */ 84 MuleMessageFactory createMuleMessageFactory() throws CreateException; 85 86 /** 87 * @return the primary protocol name for endpoints of this connector 88 */ 89 String getProtocol(); 90 91 /** 92 * @return true if the protocol is supported by this connector. 93 */ 94 boolean supportsProtocol(String protocol); 95 96 /** 97 * @param exception the exception that was caught 98 */ 99 void handleException(Exception exception); 100 101 /** 102 * The dispatcher factory is used to create a message dispatcher of the current 103 * request 104 * 105 * @param factory the factory to use when a dispatcher request is madr 106 */ 107 void setDispatcherFactory(MessageDispatcherFactory factory); 108 109 /** 110 * The dispatcher factory is used to create a message dispatcher of the current 111 * request 112 * 113 * @return the factory to use when a dispatcher request is madr 114 */ 115 MessageDispatcherFactory getDispatcherFactory(); 116 117 /** 118 * The requester factory is used to create a message requester of the current 119 * request 120 * 121 * @param factory the factory to use when a request is made 122 */ 123 void setRequesterFactory(MessageRequesterFactory factory); 124 125 /** 126 * The requester factory is used to create a message requester of the current 127 * request 128 * 129 * @return the factory to use when a request is made 130 */ 131 MessageRequesterFactory getRequesterFactory(); 132 133 boolean isResponseEnabled(); 134 135 /** 136 * Make a specific request to the underlying transport 137 * 138 * @param uri the endpoint uri to use when connecting to the resource 139 * @param timeout the maximum time the operation should block before returning. 140 * The call should return immediately if there is data available. If 141 * no data becomes available before the timeout elapses, null will be 142 * returned 143 * @return the result of the request wrapped in a MuleMessage object. Null will be 144 * returned if no data was avaialable 145 * @throws Exception if the call to the underlying protocal cuases an exception 146 * @deprecated Use request(ImmutableEndpoint endpoint, long timeout) 147 */ 148 @Deprecated 149 MuleMessage request(String uri, long timeout) throws Exception; 150 151 /** 152 * Make a specific request to the underlying transport 153 * 154 * @param endpoint the endpoint to use when connecting to the resource 155 * @param timeout the maximum time the operation should block before returning. 156 * The call should return immediately if there is data available. If 157 * no data becomes available before the timeout elapses, null will be 158 * returned 159 * @return the result of the request wrapped in a MuleMessage object. Null will be 160 * returned if no data was avaialable 161 * @throws Exception if the call to the underlying protocal cuases an exception 162 */ 163 MuleMessage request(InboundEndpoint endpoint, long timeout) throws Exception; 164 165 /** 166 * Will get the output stream for this type of transport. Typically this 167 * will be called only when Streaming is being used on an outbound endpoint. 168 * If Streaming is not supported by this transport an {@link UnsupportedOperationException} 169 * is thrown. Note that the stream MUST release resources on close. For help doing so, see 170 * {@link org.mule.model.streaming.CallbackOutputStream}. 171 * 172 * @param endpoint the endpoint that releates to this Dispatcher 173 * @param message the current message being processed 174 * @return the output stream to use for this request 175 * @throws MuleException 176 */ 177 OutputStream getOutputStream(OutboundEndpoint endpoint, MuleEvent event) throws MuleException; 178 179 MuleContext getMuleContext(); 180 181 RetryPolicyTemplate getRetryPolicyTemplate(); 182 183 /** 184 * @return the default {@link MessageExchangePattern} as configured in the 185 * transport's service descriptor. 186 */ 187 MessageExchangePattern getDefaultExchangePattern(); 188 189 /** 190 * @return List of exchange patterns that this connector supports for inbound endpoints. 191 */ 192 List<MessageExchangePattern> getInboundExchangePatterns(); 193 194 /** 195 * @return List of exchange patterns that this connector supports for outbound endpoints. 196 */ 197 List<MessageExchangePattern> getOutboundExchangePatterns(); 198 199 /** 200 * @return The strategy used for reading and writing session information to and from the transport. 201 */ 202 SessionHandler getSessionHandler(); 203 }