Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Connector |
|
| 1.0;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 | } |