Coverage Report - org.mule.api.transport.Connector
 
Classes in this File Line Coverage Branch Coverage Complexity
Connector
N/A
N/A
1
 
 1  
 /*
 2  
  * $Id: Connector.java 12294 2008-07-11 08:30:31Z 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.api.transport;
 12  
 
 13  
 import org.mule.api.MessagingException;
 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.context.MuleContextAware;
 20  
 import org.mule.api.endpoint.InboundEndpoint;
 21  
 import org.mule.api.endpoint.OutboundEndpoint;
 22  
 import org.mule.api.lifecycle.Lifecycle;
 23  
 import org.mule.api.service.Service;
 24  
 
 25  
 import java.beans.ExceptionListener;
 26  
 import java.io.OutputStream;
 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, MuleContextAware, NamedObject
 33  
 {
 34  
     int INT_VALUE_NOT_SET = -1;
 35  
 
 36  
     /**
 37  
      * This creates a <code>MessageReceiver</code> associated with this endpoint
 38  
      * and registers it with the connector
 39  
      * 
 40  
      * @param service the listening service
 41  
      * @param endpoint the endpoint contains the listener endpointUri on which to
 42  
      *            listen on.
 43  
      * @throws Exception if the MessageReceiver cannot be created or the Receiver
 44  
      *             cannot be registered
 45  
      */
 46  
     MessageReceiver registerListener(Service service, InboundEndpoint endpoint) throws Exception;
 47  
 
 48  
     /**
 49  
      * @param service the listening service
 50  
      * @param endpoint the associated endpointDescriptor with the listener
 51  
      * @throws Exception if the listener cannot be unregistered. If a listener is not
 52  
      *             associated with the given endpoint this will not throw an
 53  
      *             exception
 54  
      */
 55  
     void unregisterListener(Service service, InboundEndpoint endpoint) throws Exception;
 56  
 
 57  
     /**
 58  
      * @return true if the endpoint is started
 59  
      */
 60  
     boolean isStarted();
 61  
 
 62  
     /**
 63  
      * @return false if the connector is alive and well or true if the connector is
 64  
      *         being destroyed
 65  
      */
 66  
     boolean isDisposed();
 67  
 
 68  
     /**
 69  
      * @return false if the connector is alive and well or true if the connector has
 70  
      *         been told to dispose
 71  
      */
 72  
     boolean isDisposing();
 73  
 
 74  
     /**
 75  
      * Gets a {@link MessageAdapter} from the connector for the given message
 76  
      * (data)
 77  
      * 
 78  
      * @param message the data with which to initialise the {@link MessageAdapter}
 79  
      * @return the {@link MessageAdapter} for the endpoint
 80  
      * @throws MessagingException if the message parameter is not supported
 81  
      * @see MessageAdapter
 82  
      */
 83  
     MessageAdapter getMessageAdapter(Object message) throws MessagingException;
 84  
 
 85  
     /**
 86  
      * @return the primary protocol name for endpoints of this connector
 87  
      */
 88  
     String getProtocol();
 89  
 
 90  
     /**
 91  
      * @return true if the protocol is supported by this connector.
 92  
      */
 93  
     boolean supportsProtocol(String protocol);
 94  
 
 95  
     /**
 96  
      * @param listener the exception strategy to use with this endpoint
 97  
      * @see ExceptionListener
 98  
      */
 99  
     void setExceptionListener(ExceptionListener listener);
 100  
 
 101  
     /**
 102  
      * @return the Exception stategy used by the endpoint
 103  
      * @see ExceptionListener
 104  
      */
 105  
     ExceptionListener getExceptionListener();
 106  
 
 107  
     /**
 108  
      * @param exception the exception that was caught
 109  
      */
 110  
     void handleException(Exception exception);
 111  
 
 112  
     /**
 113  
      * The dispatcher factory is used to create a message dispatcher of the current
 114  
      * request
 115  
      * 
 116  
      * @param factory the factory to use when a dispatcher request is madr
 117  
      */
 118  
     void setDispatcherFactory(MessageDispatcherFactory factory);
 119  
 
 120  
     /**
 121  
      * The dispatcher factory is used to create a message dispatcher of the current
 122  
      * request
 123  
      * 
 124  
      * @return the factory to use when a dispatcher request is madr
 125  
      */
 126  
     MessageDispatcherFactory getDispatcherFactory();
 127  
 
 128  
     /**
 129  
      * The requester factory is used to create a message requester of the current
 130  
      * request
 131  
      *
 132  
      * @param factory the factory to use when a request is made
 133  
      */
 134  
     void setRequesterFactory(MessageRequesterFactory factory);
 135  
 
 136  
     /**
 137  
      * The requester factory is used to create a message requester of the current
 138  
      * request
 139  
      *
 140  
      * @return the factory to use when a request is made
 141  
      */
 142  
     MessageRequesterFactory getRequesterFactory();
 143  
 
 144  
     boolean isRemoteSyncEnabled();
 145  
     
 146  
     /**
 147  
      * Used to define is this connectors endpoints' should be synchronous by default rather than 
 148  
      * using Mule's instance wide default. The endpoint is passed through to this method so that 
 149  
      * transports like Axis/CXF can determine if synchronous should be default depending on the 
 150  
      * endpoint transport e.g. http/vm/jms etc.
 151  
      * 
 152  
      * @param endpoint
 153  
      * @return
 154  
      * @see ImmutableEndpoint#isSynchronous()
 155  
      */
 156  
     boolean isSyncEnabled(String protocol);
 157  
 
 158  
     /**
 159  
      * Dispatches an event from the endpoint to the external system
 160  
      * 
 161  
      * @param event The event to dispatch
 162  
      * @throws DispatchException if the event fails to be dispatched
 163  
      */
 164  
     void dispatch(OutboundEndpoint endpoint, MuleEvent event) throws DispatchException;
 165  
 
 166  
     /**
 167  
      * Make a specific request to the underlying transport
 168  
      *
 169  
      * @param uri the endpoint uri to use when connecting to the resource
 170  
      * @param timeout the maximum time the operation should block before returning.
 171  
      *            The call should return immediately if there is data available. If
 172  
      *            no data becomes available before the timeout elapses, null will be
 173  
      *            returned
 174  
      * @return the result of the request wrapped in a MuleMessage object. Null will be
 175  
      *         returned if no data was avaialable
 176  
      * @throws Exception if the call to the underlying protocal cuases an exception
 177  
      * @deprecated Use request(ImmutableEndpoint endpoint, long timeout)
 178  
      */
 179  
     MuleMessage request(String uri, long timeout) throws Exception;
 180  
 
 181  
     /**
 182  
      * Make a specific request to the underlying transport
 183  
      *
 184  
      * @param endpoint the endpoint to use when connecting to the resource
 185  
      * @param timeout the maximum time the operation should block before returning.
 186  
      *            The call should return immediately if there is data available. If
 187  
      *            no data becomes available before the timeout elapses, null will be
 188  
      *            returned
 189  
      * @return the result of the request wrapped in a MuleMessage object. Null will be
 190  
      *         returned if no data was avaialable
 191  
      * @throws Exception if the call to the underlying protocal cuases an exception
 192  
      */
 193  
     MuleMessage request(InboundEndpoint endpoint, long timeout) throws Exception;
 194  
 
 195  
     /**
 196  
      * Sends an event from the endpoint to the external system
 197  
      * 
 198  
      * @param event The event to send
 199  
      * @return event the response form the external system wrapped in a MuleEvent
 200  
      * @throws DispatchException if the event fails to be dispatched
 201  
      */
 202  
     MuleMessage send(OutboundEndpoint endpoint, MuleEvent event) throws DispatchException;
 203  
 
 204  
 
 205  
     /**
 206  
      * Will get the output stream for this type of transport. Typically this
 207  
      * will be called only when Streaming is being used on an outbound endpoint.
 208  
      * If Streaming is not supported by this transport an {@link UnsupportedOperationException}
 209  
      * is thrown.   Note that the stream MUST release resources on close.  For help doing so, see
 210  
      * {@link org.mule.model.streaming.CallbackOutputStream}.
 211  
      *
 212  
      * @param endpoint the endpoint that releates to this Dispatcher
 213  
      * @param message the current message being processed
 214  
      * @return the output stream to use for this request
 215  
      * @throws MuleException
 216  
      */
 217  
     OutputStream getOutputStream(OutboundEndpoint endpoint, MuleMessage message) throws MuleException;
 218  
 
 219  
     MuleContext getMuleContext();
 220  
 }