View Javadoc

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