View Javadoc

1   /*
2    * $Id: ImmutableEndpoint.java 12269 2008-07-10 04:19:03Z dfeist $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSource, Inc.  All rights reserved.  http://www.mulesource.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.api.MuleContext;
14  import org.mule.api.routing.filter.Filter;
15  import org.mule.api.security.EndpointSecurityFilter;
16  import org.mule.api.transaction.TransactionConfig;
17  import org.mule.api.transport.ConnectionStrategy;
18  import org.mule.api.transport.Connector;
19  
20  import java.io.Serializable;
21  import java.util.List;
22  import java.util.Map;
23  
24  /**
25   * <code>ImmutableEndpoint</code> describes a Message endpoint where data is
26   * sent or received. An Enpoint is an Resource address (EndpointUri), with associated
27   * transformation, transaction and filtering rules.
28   */
29  public interface ImmutableEndpoint extends Serializable
30  {
31  
32      String INITIAL_STATE_STARTED = "started";
33      String INITIAL_STATE_STOPPED = "stopped";
34  
35      /**
36       * This specifess the communication endpointUri. This will have a different format
37       * depending on the transport protocol being used i.e.
38       * <ul>
39       * <li>smtp -&gt; admin&#64;mycompany.com</li>
40       * <li>jms -&gt; shipping.orders.topic</li>
41       * <li>sms -&gt; +447910010010</li>
42       * </ul>
43       * <p/> if an endpointUri is not specifed it will be assumed that it will be
44       * determined at run-time by the calling application. The endpointUri can be
45       * aliteral endpointUri such as an email address or it can be a logical name for
46       * an endpointUri as long as it is declared in a <i>message-endpointUri</i>
47       * block. When the message-provider is created the endpointUri is first lookup in
48       * the endpointUri registry and if nothing is returned the endpointUri value
49       * itself is used.
50       *
51       * @return the endpointUri on which the endpoint sends or receives data
52       */
53      EndpointURI getEndpointURI();
54  
55      /**
56       * Decides the encoding to be used for events received by this endpoint
57       *
58       * @return the encoding set on the endpoint or null if no codin has been
59       *         specified
60       */
61      String getEncoding();
62  
63      /**
64       * The endpoint that will be used to send the message on. It is important that
65       * the endpointUri and the connection correlate i.e. if your endpointUri is a jms
66       * queue your connection must be a JMS endpoint.
67       *
68       * @return the endpoint associated with the endpoint
69       */
70      Connector getConnector();
71  
72      /**
73       * The name is the identifier for the endpoint
74       *
75       * @return the endpoint name
76       */
77      String getName();
78  
79      /**
80       * Transformers are responsible for transforming data when it is received or
81       * sent by the UMO (depending on whether this endpoint is a receiver or not). A
82       * tranformation for an inbound event can be forced by the user by calling the
83       * inbound event.getTransformedMessage(). A tranformation for an outbound event
84       * is called or when the UMO dispatchEvent() or sendEvent() methods are called.
85       * If an endpoint has no transformers an empty list is returned.
86       *
87       * @return the transformers to use when receiving or sending data
88       */
89      List getTransformers();
90  
91      /**
92       * The transformers used when a response is returned from invoking this endpoint.
93       * If an endpoint has no response transformers an empty list is returned.
94       * @return the transformer to use when receiving the response data
95       */
96      List getResponseTransformers();
97  
98      /**
99       * Returns any properties set on this endpoint
100      *
101      * @return a map of properties for this endpoint
102      */
103     Map getProperties();
104 
105     /**
106      * Retrieves a property set on the endpoint
107      *
108      * @param key the name of the property
109      * @return the property value or null if it does not exist
110      */
111     Object getProperty(Object key);
112 
113     /**
114      * The transport protocol name that the message endpoint communicates over. i.e.
115      * jms, sms, smtp etc. The protocol must match that of the associated endpoint
116      *
117      * @return the protocol name
118      */
119     String getProtocol();
120 
121     /**
122      * @return true if this endpoint is read-only and none of it's properties can
123      *         change. Global endpoints should be read-only so that unexpected
124      *         behaviour is avoided.
125      */
126     boolean isReadOnly();
127 
128     /**
129      * Returns the transaction configuration for this endpoint
130      *
131      * @return the transaction configuration for this endpoint or null if the
132      *         endpoint is not transactional
133      */
134     TransactionConfig getTransactionConfig();
135 
136     /**
137      * The filter to apply to incoming messages. Only applies when the endpoint
138      * endpointUri is a receiver
139      *
140      * @return the Filter to use or null if one is not set
141      */
142     Filter getFilter();
143 
144     /**
145      * If a filter is configured on this endpoint, this property will determine if
146      * message that are not excepted by the filter are deleted
147      *
148      * @return true if message should be deleted, false otherwise
149      */
150     boolean isDeleteUnacceptedMessages();
151 
152     /**
153      * Returns an EndpointSecurityFilter for this endpoint. If one is not set,
154      * there will be no authentication on events sent via this endpoint
155      *
156      * @return EndpointSecurityFilter responsible for authenticating message flow
157      *         via this endpoint.
158      * @see EndpointSecurityFilter
159      */
160     EndpointSecurityFilter getSecurityFilter();
161 
162     /**
163      * Determines if requests originating from this endpoint should be synchronous
164      * i.e. execute in a single thread and possibly return an result. This property
165      * is only used when the endpoint is of type 'receiver'
166      *
167      * @return whether requests on this endpoint should execute in a single thread.
168      *         This property is only used when the endpoint is of type 'receiver'
169      */
170     boolean isSynchronous();
171 
172     /**
173      * For certain providers that support the notion of a backchannel such as sockets
174      * (outputStream) or Jms (ReplyTo) Mule can automatically wait for a response
175      * from a backchannel when dispatching over these protocols. This is different
176      * for synchronous as synchronous behavior only applies to in
177      *
178      */
179     boolean isRemoteSync();
180 
181     /**
182      * The timeout value for remoteSync invocations
183      *
184      * @return the timeout in milliseconds
185      */
186     int getRemoteSyncTimeout();
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      * Returns the connection strategy this endpoint should use when connecting to the underlying resource
200      * @return the connection strategy this endpoint should use when connecting to the underlying resource
201      */
202     ConnectionStrategy getConnectionStrategy();
203 }