View Javadoc

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 }