View Javadoc

1   /*
2    * $Id: Connector.java 19704 2010-09-22 19:26:15Z tcarlson $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.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.MessageExchangePattern;
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.construct.FlowConstruct;
20  import org.mule.api.endpoint.InboundEndpoint;
21  import org.mule.api.endpoint.OutboundEndpoint;
22  import org.mule.api.lifecycle.CreateException;
23  import org.mule.api.lifecycle.Lifecycle;
24  import org.mule.api.lifecycle.LifecycleStateEnabled;
25  import org.mule.api.processor.MessageProcessor;
26  import org.mule.api.retry.RetryPolicyTemplate;
27  
28  import java.io.OutputStream;
29  import java.util.List;
30  
31  /**
32   * <code>Connector</code> is the mechanism used to connect to external systems
33   * and protocols in order to send and receive data.
34   */
35  public interface Connector extends Lifecycle, NamedObject, Connectable, LifecycleStateEnabled
36  {
37      int INT_VALUE_NOT_SET = -1;
38  
39      /**
40       * Registers a MessageProcessor listener which will listen to new message
41       * received from a specific transport channel and then processed by the endpoint.
42       * Only a single listener can be registered for a given endpoints. Attempts to
43       * register a listener when one is already registered will fail.
44       * 
45       * @param endpoint defines both the transport and channel/resource uri as well
46       *            the processing (transformation/filtering) that should occur when
47       *            the endpoint processes a new message from the transport receiver.
48       * @param listener the listener that will be invoked when messages are received
49       *            on the endpoint.
50       * @param pattern reference to the runtime construct that the listener is part of
51       *            for use as context for logging, notifications and error handling.
52       * @throws Exception
53       */
54      public void registerListener(InboundEndpoint endpoint, MessageProcessor listener, FlowConstruct flowConstruct)
55          throws Exception;
56  
57      /**
58       * Unregisters the listener for the given endpoints. This will mean that the
59       * listener that was registered for this endpoint will no longer receive any
60       * messages.
61       * 
62       * @param endpoint
63       * @throws Exception
64       */
65      public void unregisterListener(InboundEndpoint endpoint, FlowConstruct flowConstruct) throws Exception;
66  
67      /**
68       * @return true if the endpoint is started
69       */
70      boolean isStarted();
71  
72      boolean isConnected();
73  
74      /**
75       * @return false if the connector is alive and well or true if the connector is
76       *         being destroyed
77       */
78      boolean isDisposed();
79  
80      /**
81       * Creates a new {@link MuleMessageFactory} using what's defined in the connector's 
82       * transport service descriptor. 
83       */
84      MuleMessageFactory createMuleMessageFactory() throws CreateException;
85      
86      /**
87       * @return the primary protocol name for endpoints of this connector
88       */
89      String getProtocol();
90  
91      /**
92       * @return true if the protocol is supported by this connector.
93       */
94      boolean supportsProtocol(String protocol);
95  
96      /**
97       * @param exception the exception that was caught
98       */
99      void handleException(Exception exception);
100 
101     /**
102      * The dispatcher factory is used to create a message dispatcher of the current
103      * request
104      * 
105      * @param factory the factory to use when a dispatcher request is madr
106      */
107     void setDispatcherFactory(MessageDispatcherFactory factory);
108 
109     /**
110      * The dispatcher factory is used to create a message dispatcher of the current
111      * request
112      * 
113      * @return the factory to use when a dispatcher request is madr
114      */
115     MessageDispatcherFactory getDispatcherFactory();
116 
117     /**
118      * The requester factory is used to create a message requester of the current
119      * request
120      *
121      * @param factory the factory to use when a request is made
122      */
123     void setRequesterFactory(MessageRequesterFactory factory);
124 
125     /**
126      * The requester factory is used to create a message requester of the current
127      * request
128      *
129      * @return the factory to use when a request is made
130      */
131     MessageRequesterFactory getRequesterFactory();
132 
133     boolean isResponseEnabled();
134     
135     /**
136      * Make a specific request to the underlying transport
137      *
138      * @param uri the endpoint uri to use when connecting to the resource
139      * @param timeout the maximum time the operation should block before returning.
140      *            The call should return immediately if there is data available. If
141      *            no data becomes available before the timeout elapses, null will be
142      *            returned
143      * @return the result of the request wrapped in a MuleMessage object. Null will be
144      *         returned if no data was avaialable
145      * @throws Exception if the call to the underlying protocal cuases an exception
146      * @deprecated Use request(ImmutableEndpoint endpoint, long timeout)
147      */
148     @Deprecated
149     MuleMessage request(String uri, long timeout) throws Exception;
150 
151     /**
152      * Make a specific request to the underlying transport
153      *
154      * @param endpoint the endpoint to use when connecting to the resource
155      * @param timeout the maximum time the operation should block before returning.
156      *            The call should return immediately if there is data available. If
157      *            no data becomes available before the timeout elapses, null will be
158      *            returned
159      * @return the result of the request wrapped in a MuleMessage object. Null will be
160      *         returned if no data was avaialable
161      * @throws Exception if the call to the underlying protocal cuases an exception
162      */
163     MuleMessage request(InboundEndpoint endpoint, long timeout) throws Exception;
164 
165     /**
166      * Will get the output stream for this type of transport. Typically this
167      * will be called only when Streaming is being used on an outbound endpoint.
168      * If Streaming is not supported by this transport an {@link UnsupportedOperationException}
169      * is thrown.   Note that the stream MUST release resources on close.  For help doing so, see
170      * {@link org.mule.model.streaming.CallbackOutputStream}.
171      *
172      * @param endpoint the endpoint that releates to this Dispatcher
173      * @param message the current message being processed
174      * @return the output stream to use for this request
175      * @throws MuleException
176      */
177     OutputStream getOutputStream(OutboundEndpoint endpoint, MuleEvent event) throws MuleException;
178 
179     MuleContext getMuleContext();
180 
181     RetryPolicyTemplate getRetryPolicyTemplate();
182 
183     /**
184      * @return the default {@link MessageExchangePattern} as configured in the
185      *         transport's service descriptor.
186      */
187     MessageExchangePattern getDefaultExchangePattern();
188     
189     /**
190      * @return List of exchange patterns that this connector supports for inbound endpoints.
191      */
192     List<MessageExchangePattern> getInboundExchangePatterns();
193     
194     /**
195      * @return List of exchange patterns that this connector supports for outbound endpoints.
196      */
197     List<MessageExchangePattern> getOutboundExchangePatterns();
198     
199     /**
200      * @return The strategy used for reading and writing session information to and from the transport.
201      */
202     SessionHandler getSessionHandler();
203 }