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