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