1 /* 2 * $Id: UMOConnector.java 7976 2007-08-21 14:26:13Z dirk.olmes $ 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.umo.provider; 12 13 import org.mule.umo.MessagingException; 14 import org.mule.umo.UMOComponent; 15 import org.mule.umo.UMOEvent; 16 import org.mule.umo.UMOException; 17 import org.mule.umo.UMOMessage; 18 import org.mule.umo.endpoint.UMOEndpoint; 19 import org.mule.umo.endpoint.UMOEndpointURI; 20 import org.mule.umo.endpoint.UMOImmutableEndpoint; 21 import org.mule.umo.lifecycle.Disposable; 22 import org.mule.umo.lifecycle.Initialisable; 23 24 import java.beans.ExceptionListener; 25 import java.io.InputStream; 26 import java.io.OutputStream; 27 28 import edu.emory.mathcs.backport.java.util.concurrent.ScheduledExecutorService; 29 30 /** 31 * <code>UMOConnector</code> is the mechanism used to connect to external systems 32 * and protocols in order to send and receive data. 33 */ 34 public interface UMOConnector extends Disposable, Initialisable 35 { 36 int INT_VALUE_NOT_SET = -1; 37 38 /** 39 * This creates a <code>UMOMessageReceiver</code> associated with this endpoint 40 * and registers it with the connector. 41 * 42 * @param component the listening component 43 * @param endpoint the endpoint contains the listener endpointUri on which to 44 * listen on. 45 * @throws Exception if the UMOMessageReceiver cannot be created or the Receiver 46 * cannot be registered 47 * @return message receiver 48 */ 49 UMOMessageReceiver registerListener(UMOComponent component, UMOEndpoint endpoint) throws Exception; 50 51 /** 52 * @param component the listening component 53 * @param endpoint the associated endpointDescriptor with the listener 54 * @throws Exception if the listener cannot be unregistered. If a listener is not 55 * associated with the given endpoint this will not throw an 56 * exception 57 */ 58 void unregisterListener(UMOComponent component, UMOEndpoint endpoint) throws Exception; 59 60 /** 61 * @return true if the endpoint is started 62 */ 63 boolean isStarted(); 64 65 /** 66 * @return false if the connector is alive and well or true if the connector is 67 * being destroyed 68 */ 69 boolean isDisposed(); 70 71 /** 72 * @return false if the connector is alive and well or true if the connector has 73 * been told to dispose 74 */ 75 boolean isDisposing(); 76 77 /** 78 * Gets a {@link UMOMessageAdapter} from the connector for the given message 79 * (data) 80 * 81 * @param message the data with which to initialise the {@link UMOMessageAdapter} 82 * @return the {@link UMOMessageAdapter} for the endpoint 83 * @throws MessagingException if the message parameter is not supported 84 * @see UMOMessageAdapter 85 */ 86 UMOMessageAdapter getMessageAdapter(Object message) throws MessagingException; 87 88 /** 89 * Gets a {@link UMOStreamMessageAdapter} from the connector for the given 90 * message. This Adapter will correctly handle data streaming for this type of 91 * connector 92 * 93 * @param in the input stream to read the data from 94 * @param out the outputStream to write data to. This can be null. 95 * @return the {@link UMOStreamMessageAdapter} for the endpoint 96 * @throws MessagingException if the message parameter is not supported 97 * @see UMOStreamMessageAdapter 98 */ 99 UMOStreamMessageAdapter getStreamMessageAdapter(InputStream in, OutputStream out) 100 throws MessagingException; 101 102 /** 103 * @return the name associated with the connector 104 */ 105 String getName(); 106 107 /** 108 * @param newName the name to associate with the connector 109 */ 110 void setName(String newName); 111 112 /** 113 * @return the primary protocol name for endpoints of this connector 114 */ 115 String getProtocol(); 116 117 /** 118 * @param protocol protocol name 119 * @return true if the protocol is supported by this connector. 120 */ 121 boolean supportsProtocol(String protocol); 122 123 /** 124 * @param listener the exception strategy to use with this endpoint 125 * @see ExceptionListener 126 */ 127 void setExceptionListener(ExceptionListener listener); 128 129 /** 130 * @return the Exception stategy used by the endpoint 131 * @see ExceptionListener 132 */ 133 ExceptionListener getExceptionListener(); 134 135 /** 136 * @param exception the exception that was caught 137 */ 138 void handleException(Exception exception); 139 140 /** 141 * Returns a Scheduler service for execution of periodic tasks. 142 * @return scheduler 143 */ 144 ScheduledExecutorService getScheduler(); 145 146 /** 147 * The dispatcher factory is used to create a message dispatcher of the current 148 * request 149 * 150 * @param factory the factory to use when a dispatcher request is madr 151 */ 152 void setDispatcherFactory(UMOMessageDispatcherFactory factory); 153 154 /** 155 * The dispatcher factory is used to create a message dispatcher of the current 156 * request 157 * 158 * @return the factory to use when a dispatcher request is madr 159 */ 160 UMOMessageDispatcherFactory getDispatcherFactory(); 161 162 void startConnector() throws UMOException; 163 164 void stopConnector() throws UMOException; 165 166 boolean isRemoteSyncEnabled(); 167 168 /** 169 * Dispatches an event from the endpoint to the external system 170 * 171 * @param event The event to dispatch 172 * @param endpoint endpoint to dispatch from 173 * @throws DispatchException if the event fails to be dispatched 174 */ 175 void dispatch(UMOImmutableEndpoint endpoint, UMOEvent event) throws DispatchException; 176 177 /** 178 * Make a specific request to the underlying transport 179 * 180 * @param endpointUri the endpoint URI to use when connecting to the resource 181 * @param timeout the maximum time the operation should block before returning. 182 * The call should return immediately if there is data available. If 183 * no data becomes available before the timeout elapses, null will be 184 * returned 185 * @return the result of the request wrapped in a UMOMessage object. Null will be 186 * returned if no data was avaialable 187 * @throws Exception if the call to the underlying protocal cuases an exception 188 * @deprecated Use receive(UMOImmutableEndpoint endpoint, long timeout) 189 */ 190 UMOMessage receive(UMOEndpointURI endpointUri, long timeout) throws Exception; 191 192 /** 193 * Make a specific request to the underlying transport 194 * 195 * @param endpoint the endpoint to use when connecting to the resource 196 * @param timeout the maximum time the operation should block before returning. 197 * The call should return immediately if there is data available. If 198 * no data becomes available before the timeout elapses, null will be 199 * returned 200 * @return the result of the request wrapped in a UMOMessage object. Null will be 201 * returned if no data was avaialable 202 * @throws Exception if the call to the underlying protocal cuases an exception 203 */ 204 UMOMessage receive(UMOImmutableEndpoint endpoint, long timeout) throws Exception; 205 206 /** 207 * Sends an event from the endpoint to the external system 208 * 209 * @param event The event to send 210 * @param endpoint endpoint to send from 211 * @return event the response form the external system wrapped in a UMOEvent 212 * @throws DispatchException if the event fails to be dispatched 213 */ 214 UMOMessage send(UMOImmutableEndpoint endpoint, UMOEvent event) throws DispatchException; 215 216 217 /** 218 * Will get the output stream for this type of transport. Typically this 219 * will be called only when Streaming is being used on an outbound endpoint. 220 * If Streaming is not supported by this transport an {@link UnsupportedOperationException} 221 * is thrown. Note that the stream MUST release resources on close. For help doing so, see 222 * {@link org.mule.impl.model.streaming.CallbackOutputStream}. 223 * 224 * @param endpoint the endpoint that releates to this Dispatcher 225 * @param message the current message being processed 226 * @return the output stream to use for this request 227 * @throws UMOException in case of any error 228 */ 229 OutputStream getOutputStream(UMOImmutableEndpoint endpoint, UMOMessage message) throws UMOException; 230 231 }