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