Coverage Report - org.mule.umo.provider.UMOConnector
 
Classes in this File Line Coverage Branch Coverage Complexity
UMOConnector
N/A
N/A
1
 
 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  
 }