View Javadoc

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