View Javadoc

1   /*
2    * $Id: ImmutableEndpoint.java 22826 2011-09-02 07:30:19Z mike.schilling $
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.endpoint;
12  
13  import org.mule.MessageExchangePattern;
14  import org.mule.api.MuleContext;
15  import org.mule.api.NamedObject;
16  import org.mule.api.processor.MessageProcessor;
17  import org.mule.api.retry.RetryPolicyTemplate;
18  import org.mule.api.routing.filter.Filter;
19  import org.mule.api.security.EndpointSecurityFilter;
20  import org.mule.api.transaction.TransactionConfig;
21  import org.mule.api.transformer.Transformer;
22  import org.mule.api.transport.Connector;
23  import org.mule.processor.AbstractRedeliveryPolicy;
24  
25  import java.io.Serializable;
26  import java.util.List;
27  import java.util.Map;
28  
29  /**
30   * <code>ImmutableEndpoint</code> describes a Message endpoint where data is
31   * sent or received. An Enpoint is an Resource address (EndpointUri), with associated
32   * transformation, transaction and filtering rules.
33   */
34  public interface ImmutableEndpoint extends Serializable, NamedObject
35  {
36  
37      String INITIAL_STATE_STARTED = "started";
38      String INITIAL_STATE_STOPPED = "stopped";
39  
40      /**
41       * This specifess the communication endpointUri. This will have a different format
42       * depending on the transport protocol being used i.e.
43       * <ul>
44       * <li>smtp -&gt; admin&#64;mycompany.com</li>
45       * <li>jms -&gt; shipping.orders.topic</li>
46       * <li>sms -&gt; +447910010010</li>
47       * </ul>
48       * <p/> if an endpointUri is not specifed it will be assumed that it will be
49       * determined at run-time by the calling application. The endpointUri can be
50       * aliteral endpointUri such as an email address or it can be a logical name for
51       * an endpointUri as long as it is declared in a <i>message-endpointUri</i>
52       * block. When the message-provider is created the endpointUri is first lookup in
53       * the endpointUri registry and if nothing is returned the endpointUri value
54       * itself is used.
55       *
56       * @return the endpointUri on which the endpoint sends or receives data
57       */
58      EndpointURI getEndpointURI();
59  
60      /**
61       * This returns the address of the endpoint.  When this contains a template, it may not be a URI
62       *
63       * @return the address on which the endpoint sends or receives data
64       */
65      String getAddress();
66  
67      /**
68       * Decides the encoding to be used for events received by this endpoint
69       *
70       * @return the encoding set on the endpoint or null if no codin has been
71       *         specified
72       */
73      String getEncoding();
74  
75      /**
76       * The endpoint that will be used to send the message on. It is important that
77       * the endpointUri and the connection correlate i.e. if your endpointUri is a jms
78       * queue your connection must be a JMS endpoint.
79       *
80       * @return the endpoint associated with the endpoint
81       */
82      Connector getConnector();
83  
84      /**
85       * Transformers are responsible for transforming data when it is received or
86       * sent by the component (depending on whether this endpoint is a receiver or not). A
87       * tranformation for an inbound event can be forced by the user by calling the
88       * inbound event.getTransformedMessage(). A tranformation for an outbound event
89       * is called or when the Service dispatchEvent() or sendEvent() methods are called.
90       * If an endpoint has no transformers an empty list is returned.
91       *
92       * @return the transformers to use when receiving or sending data
93       * @deprecated use getMessageProcessors() instead
94       */
95      List<Transformer> getTransformers();
96  
97      /**
98       * The transformers used when a response is returned from invoking this endpoint.
99       * If an endpoint has no response transformers an empty list is returned.
100      *
101      * @return the transformer to use when receiving the response data
102      * @deprecated use getResponseMessageProcessors() instead
103      */
104     List<Transformer> getResponseTransformers();
105 
106     /**
107      * Returns any properties set on this endpoint
108      *
109      * @return a map of properties for this endpoint
110      */
111     Map getProperties();
112 
113     /**
114      * Retrieves a property set on the endpoint
115      *
116      * @param key the name of the property
117      * @return the property value or null if it does not exist
118      */
119     Object getProperty(Object key);
120 
121     /**
122      * The transport protocol name that the message endpoint communicates over. i.e.
123      * jms, sms, smtp etc. The protocol must match that of the associated endpoint
124      *
125      * @return the protocol name
126      */
127     String getProtocol();
128 
129     /**
130      * @return true if this endpoint is read-only and none of it's properties can
131      *         change. Global endpoints should be read-only so that unexpected
132      *         behaviour is avoided.
133      */
134     boolean isReadOnly();
135 
136     /**
137      * Returns the transaction configuration for this endpoint
138      *
139      * @return the transaction configuration for this endpoint or null if the
140      *         endpoint is not transactional
141      */
142     TransactionConfig getTransactionConfig();
143 
144     /**
145      * The filter to apply to incoming messages. Only applies when the endpoint
146      * endpointUri is a receiver
147      *
148      * @return the Filter to use or null if one is not set
149      */
150     Filter getFilter();
151 
152     /**
153      * If a filter is configured on this endpoint, this property will determine if
154      * message that are not excepted by the filter are deleted
155      *
156      * @return true if message should be deleted, false otherwise
157      */
158     boolean isDeleteUnacceptedMessages();
159 
160     /**
161      * Returns an EndpointSecurityFilter for this endpoint. If one is not set,
162      * there will be no authentication on events sent via this endpoint
163      *
164      * @return EndpointSecurityFilter responsible for authenticating message flow
165      *         via this endpoint.
166      * @see EndpointSecurityFilter
167      */
168     @Deprecated
169     EndpointSecurityFilter getSecurityFilter();
170 
171     EndpointMessageProcessorChainFactory getMessageProcessorsFactory();
172 
173     List <MessageProcessor> getMessageProcessors();
174     
175     List <MessageProcessor> getResponseMessageProcessors();
176     
177     MessageExchangePattern getExchangePattern();
178     
179     /**
180      * The timeout value for waiting for a response from a remote invocation or back channel. Mule 
181      * will only wait for a response if the endpoint's message exchange pattern requires a 
182      * response.
183      *
184      * @return the timeout in milliseconds
185      */
186     int getResponseTimeout();
187 
188     /**
189      * Sets the state the endpoint will be loaded in. The States are 'stopped' and
190      * 'started' (default)
191      *
192      * @return the endpoint starting state
193      */
194     String getInitialState();
195 
196     MuleContext getMuleContext();
197 
198     /**
199      * The retry policy on the endpoint configures how retries are handled. The behaviour is slightly different
200      * for inbound and outbound endpoints.
201      * For inbound endpoints the Retry Policy determines how the connection to the underlying transport will be
202      * managed if the connection is lost.
203      * For outbound endpoints, the Retry Policy will attempt to retry dispatching, sending and receiving an event
204      *
205      * @return the Policy factory to use when retrying a connection or dispatching an event
206      */
207     RetryPolicyTemplate getRetryPolicyTemplate();
208 
209     /**
210      * The name of the endpoint builder used to create this endpoint. May be used to
211      * an endpoints builder for example to recreate endpoints for deserialized events.
212      */
213     String getEndpointBuilderName();
214 
215     boolean isProtocolSupported(String protocol);
216 
217     /**
218      * Return the mime type defined for the endpoint, if any
219      */
220     String getMimeType();
221 
222     /**
223      * Return the endpoint's redelivery policy, if any
224      */
225     AbstractRedeliveryPolicy getRedeliveryPolicy();
226 
227     boolean isDisableTransportTransformer();
228 }