View Javadoc

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