View Javadoc

1   /*
2    * $Id: UMOImmutableEndpoint.java 8335 2007-09-11 15:30:24Z holger $
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.umo.endpoint;
12  
13  import org.mule.umo.UMOFilter;
14  import org.mule.umo.UMOTransactionConfig;
15  import org.mule.umo.lifecycle.Initialisable;
16  import org.mule.umo.provider.UMOConnector;
17  import org.mule.umo.provider.UMOMessageDispatching;
18  import org.mule.umo.security.UMOEndpointSecurityFilter;
19  import org.mule.umo.transformer.UMOTransformer;
20  
21  import java.util.Map;
22  
23  /**
24   * <code>UMOImmutableEndpoint</code> describes a Message endpoint where data is
25   * sent or received. An Enpoint is an Resource address (EndpointUri), with associated
26   * transformation, transaction and filtering rules.
27   */
28  public interface UMOImmutableEndpoint extends Cloneable, Initialisable, UMOMessageDispatching
29  {
30      String INITIAL_STATE_STARTED = "started";
31      String INITIAL_STATE_STOPPED = "stopped";
32  
33      /** The endpoint is outbound */
34      String ENDPOINT_TYPE_SENDER = "sender";
35  
36      /** The endpoint is indound */
37      String ENDPOINT_TYPE_RECEIVER = "receiver";
38  
39      /** The endpoint is either and will be set depending on how it is used */
40      String ENDPOINT_TYPE_SENDER_AND_RECEIVER = "senderAndReceiver";
41  
42      /** The endpoint is a receive endpoint set on a response router */
43      String ENDPOINT_TYPE_RESPONSE = "response";
44  
45      /**
46       * This specifes the communication endpointUri. This will have a different format
47       * depending on the transport protocol being used i.e.
48       * <ul>
49       * <li>smtp -&gt; admin&#64;mycompany.com</li>
50       * <li>jms -&gt; shipping.orders.topic</li>
51       * <li>sms -&gt; +447910010010</li>
52       * </ul>
53       * <p/> if an endpointUri is not specifed it will be assumed that it will be
54       * determined at run-time by the calling application. The endpointUri can be
55       * aliteral endpointUri such as an email address or it can be a logical name for
56       * an endpointUri as long as it is declared in a <i>message-endpointUri</i>
57       * block. When the message-provider is created the endpointUri is first lookup in
58       * the endpointUri registry and if nothing is returned the endpointUri value
59       * itself is used.
60       * 
61       * @return the endpointUri on which the endpoint sends or receives data
62       */
63      UMOEndpointURI getEndpointURI();
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       * Determines whether the message endpoint is a sender or receiver or both. The
75       * possible values are-
76       * <ul>
77       * <li>sender - PROVIDER_TYPE_SENDER</li>
78       * <li>receiver - PROVIDER_TYPE_RECEIVER</li>
79       * <li>senderAndReceiver - PROVIDER_TYPE_SENDER_AND_RECEIVER</li>
80       * </ul>
81       * The default is 'senderAndReceiver'.
82       * 
83       * @return the endpoint type
84       */
85      String getType();
86  
87      /**
88       * The endpoint that will be used to send the message on. It is important that
89       * the endpointUri and the connection correlate i.e. if your endpointUri is a jms
90       * queue your connection must be a JMS endpoint.
91       * 
92       * @return the endpoint associated with the endpoint
93       */
94      UMOConnector getConnector();
95  
96      /**
97       * The name is the identifier for the endpoint
98       * 
99       * @return the endpoint name
100      */
101     String getName();
102 
103     /**
104      * The transformer is responsible for transforming data when it is received or
105      * sent by the UMO (depending on whether this endpoint is a receiver or not). A
106      * tranformation for an inbound event can be forced by the user by calling the
107      * inbound event.getTransformedMessage(). A tranformation for an outbound event
108      * is called or when the UMO dispatchEvent() or sendEvent() methods are called.
109      * <p/> This attribute represents the name of the transformer to use as declared
110      * in the transformers section of the configuration file. IF a name for the
111      * transformer is not set on the configuration element, it will default to the
112      * name of the className attribute minus the package name.
113      * 
114      * @return the transformer to use when receiving or sending data
115      */
116     UMOTransformer getTransformer();
117 
118     /**
119      * The transformer used when a response is returned from invoking this endpoint
120      * 
121      * @return the transformer to use when receiving the response data
122      */
123     UMOTransformer getResponseTransformer();
124 
125     /**
126      * Returns any properties set on this endpoint
127      * 
128      * @return a map of properties for this endpoint
129      */
130     Map getProperties();
131 
132     /**
133      * Retrieves a property set on the endpoint
134      * 
135      * @param key the name of the property
136      * @return the property value or null if it does not exist
137      */
138     Object getProperty(Object key);
139 
140     /**
141      * The transport protocol name that the message endpoint communicates over. i.e.
142      * jms, sms, smtp etc. The protocol must match that of the associated endpoint
143      * 
144      * @return the protocol name
145      */
146     String getProtocol();
147 
148     /**
149      * @return true if this endpoint is read-only and none of it's properties can
150      *         change. Global endpoints should be read-only so that unexpected
151      *         behaviour is avoided.
152      */
153     boolean isReadOnly();
154 
155     /**
156      * Determines whether this endpoint can be used to send events
157      * 
158      * @return true if it has been configured to send events, false otherwise
159      */
160     boolean canSend();
161 
162     /**
163      * Determines whether this endpoint can be used to receive events
164      * 
165      * @return true if it has been configured to receive events, false otherwise
166      */
167     boolean canReceive();
168 
169     /**
170      * Returns the transaction configuration for this endpoint
171      * 
172      * @return the transaction configuration for this endpoint or null if the
173      *         endpoint is not transactional
174      */
175     UMOTransactionConfig getTransactionConfig();
176 
177     /**
178      * Make a deep copy of this endpoint
179      * 
180      * @return a copy of the endpoint
181      */
182     Object clone();
183 
184     /**
185      * The filter to apply to incoming messages. Only applies when the endpoint
186      * endpointUri is a receiver
187      * 
188      * @return the UMOFilter to use or null if one is not set
189      */
190     UMOFilter getFilter();
191 
192     /**
193      * If a filter is configured on this endpoint, this property will determine if
194      * message that are not excepted by the filter are deleted
195      * 
196      * @return true if message should be deleted, false otherwise
197      */
198     boolean isDeleteUnacceptedMessages();
199 
200     /**
201      * Returns an UMOEndpointSecurityFilter for this endpoint. If one is not set,
202      * there will be no authentication on events sent via this endpoint
203      * 
204      * @return UMOEndpointSecurityFilter responsible for authenticating message flow
205      *         via this endpoint.
206      * @see UMOEndpointSecurityFilter
207      */
208     UMOEndpointSecurityFilter getSecurityFilter();
209 
210     /**
211      * Determines if requests originating from this endpoint should be synchronous
212      * i.e. execute in a single thread and possibly return an result. This property
213      * is only used when the endpoint is of type 'receiver'
214      * 
215      * @return whether requests on this endpoint should execute in a single thread.
216      *         This property is only used when the endpoint is of type 'receiver'
217      */
218     boolean isSynchronous();
219 
220     /**
221      * Determines if the synchronous porperty has been set on the endpoint
222      * 
223      * @return
224      */
225     boolean isSynchronousSet();
226 
227     /**
228      * For certain providers that support the notion of a backchannel such as sockets
229      * (outputStream) or Jms (ReplyTo) Mule can automatically wait for a response
230      * from a backchannel when dispatching over these protocols. This is different
231      * for synchronous as synchronous behavior only applies to in
232      * 
233      * @return
234      */
235     boolean isRemoteSync();
236 
237     /**
238      * The timeout value for remoteSync invocations
239      * 
240      * @return the timeout in milliseconds
241      */
242     int getRemoteSyncTimeout();
243 
244     /**
245      * Determines if a new connector is created for this endpoint or an exising one
246      * must already be present
247      * 
248      * @return
249      */
250     int getCreateConnector();
251 
252     /**
253      * Sets the state the endpoint will be loaded in. The States are 'stopped' and
254      * 'started' (default)
255      * 
256      * @return the endpoint starting state
257      */
258     String getInitialState();
259 
260     /**
261      * Determines whether the endpoint should deal with requests as streams
262      * 
263      * @return true if the request should be streamed
264      */
265     boolean isStreaming();
266 }