View Javadoc

1   /*
2    * $Id: UMOEndpoint.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.provider.UMOConnector;
16  import org.mule.umo.security.UMOEndpointSecurityFilter;
17  import org.mule.umo.transformer.UMOTransformer;
18  
19  import java.util.Map;
20  
21  /**
22   * <code>UMOEndpoint</code> describes a Provider in the Mule Server. A endpoint is
23   * a grouping of an endpoint, an endpointUri and a transformer.
24   * 
25   * @author <a href="mailto:ross.mason@symphonysoft.com">Ross Mason</a>
26   * @version $Revision: 7976 $
27   */
28  public interface UMOEndpoint extends UMOImmutableEndpoint
29  {
30      /**
31       * This specifes the communication endpointUri. This will have a different format
32       * depending on the transport protocol being used i.e.
33       * <ul>
34       * <li>smtp -&gt; smtp://admin&#64;mycompany.com</li>
35       * <li>jms -&gt; jms://shipping.orders.topic</li>
36       * <li>sms -&gt; sms://+447910010010</li>
37       * </ul>
38       * <p/> if an endpointUri is not specifed it will be assumed that it will be
39       * determined at run-time by the calling application. The endpointUri can be
40       * aliteral endpointUri such as an email address or it can be a logical name for
41       * an endpointUri as long as it is declared in a <i>message-endpointUri</i>
42       * block. When the message-provider is created the endpointUri is first lookup in
43       * the endpointUri registry and if nothing is returned the endpointUri value
44       * itself is used.
45       * 
46       * @param endpointUri the endpointUri on which the Endpoint sends or receives
47       *            data
48       * @throws EndpointException thrown if the EndpointUri cannot be processed by the
49       *             Endpoint
50       */
51      void setEndpointURI(UMOEndpointURI endpointUri) throws EndpointException;
52  
53      /**
54       * Sets the encoding to be used for events received by this endpoint
55       * 
56       * @param endpointEncoding the encoding set on the endpoint. If not set the
57       *            encoding will be taken from the manager config
58       */
59      void setEncoding(String endpointEncoding);
60  
61      /**
62       * Determines whether the message endpoint is a sender or receiver or both. The
63       * possible values are-
64       * <ul>
65       * <li>sender - PROVIDER_TYPE_SENDER</li>
66       * <li>receiver - PROVIDER_TYPE_RECEIVER</li>
67       * <li>senderAndReceiver - PROVIDER_TYPE_SENDER_AND_RECEIVER</li>
68       * </ul>
69       * 
70       * @param type the endpoint type
71       */
72      void setType(String type);
73  
74      /**
75       * The endpoint that will be used to send the message on. It is important that
76       * the endpointUri and the connection correlate i.e. if your endpointUri is a jms
77       * queue your connection must be a JMS endpoint.
78       * 
79       * @param connector the endpoint to associate with the endpoint
80       */
81      void setConnector(UMOConnector connector);
82  
83      /**
84       * @param name the name to identify the endpoint
85       */
86      void setName(String name);
87  
88      /**
89       * The transformer is responsible for transforming data when it is received or
90       * sent by the UMO (depending on whether this endpoint is a receiver or not). A
91       * tranformation for an inbound event can be forced by the user by calling the
92       * inbound event.getTransformedMessage(). A tranformation for an outbound event
93       * is called or when the UMO dispatchEvent() or sendEvent() methods are called.
94       * <p/> This attribute represents the name of the transformer to use as declared
95       * in the transformers section of the configuration file. IF a name for the
96       * transformer is not set on the configuration element, it will default to the
97       * name of the className attribute minus the package name.
98       * 
99       * @param trans the transformer to use when receiving or sending data
100      */
101     void setTransformer(UMOTransformer trans);
102 
103     /**
104      * Sets tyhe transformer used when a response is sent back from the endpoint
105      * invocation
106      * 
107      * @param trans the transformer to use
108      */
109     void setResponseTransformer(UMOTransformer trans);
110 
111     /**
112      * @param props properties for this endpoint
113      */
114     void setProperties(Map props);
115 
116     /**
117      * Returns the transaction configuration for this endpoint
118      * 
119      * @return transaction config for this endpoint
120      */
121     UMOTransactionConfig getTransactionConfig();
122 
123     /**
124      * Sets the Transaction configuration for the endpoint
125      * 
126      * @param config the transaction config to use by this endpoint
127      */
128     void setTransactionConfig(UMOTransactionConfig config);
129 
130     /**
131      * The filter to apply to incoming messages
132      * 
133      * @param filter the filter to use
134      */
135     void setFilter(UMOFilter filter);
136 
137     /**
138      * If a filter is configured on this endpoint, this property will determine if
139      * message that are not excepted by the filter are deleted
140      * 
141      * @param delete if message should be deleted, false otherwise
142      */
143     void setDeleteUnacceptedMessages(boolean delete);
144 
145     /**
146      * Sets an UMOEndpointSecurityFilter for this endpoint. If a filter is set all
147      * traffice via this endpoint with be subject to authentication.
148      * 
149      * @param filter the UMOSecurityFilter responsible for authenticating message
150      *            flow via this endpoint.
151      * @see org.mule.umo.security.UMOEndpointSecurityFilter
152      */
153     void setSecurityFilter(UMOEndpointSecurityFilter filter);
154 
155     /**
156      * Determines if requests originating from this endpoint should be synchronous
157      * i.e. execute in a single thread and possibly return an result. This property
158      * is only used when the endpoint is of type 'receiver'.
159      * 
160      * @param synchronous whether requests on this endpoint should execute in a
161      *            single thread. This property is only used when the endpoint is of
162      *            type 'receiver'
163      */
164     void setSynchronous(boolean synchronous);
165 
166     /**
167      * Sets a property on the endpoint
168      * 
169      * @param key the property key
170      * @param value the value of the property
171      */
172     void setProperty(String key, Object value);
173 
174     /**
175      * This attribute determines how a connector is obtained for the endpoint. The
176      * options are - GET_OR_CREATE_CONNECTOR = 0: create a connector for the endpoint
177      * if one isn't already register (default) ALWAYS_CREATE_CONNECTOR = 1: Always
178      * create a new connector of each endpoint NEVER_CREATE_CONNECTOR = 2: Throw an
179      * exception if there is not connector with a matching protocol for this endpoint
180      * 
181      * @param action
182      */
183     void setCreateConnector(int action);
184 
185     /**
186      * For certain providers that support the notion of a backchannel such as sockets
187      * (outputStream) or Jms (ReplyTo) Mule can automatically wait for a response
188      * from a backchannel when dispatching over these protocols. This is different
189      * for synchronous as synchronous behavior only applies to in
190      * 
191      * @param value whether the endpoint should perfrom sync receives
192      */
193     void setRemoteSync(boolean value);
194 
195     /**
196      * The timeout value for remoteSync invocations
197      * 
198      * @param timeout the timeout in milliseconds
199      */
200     void setRemoteSyncTimeout(int timeout);
201 
202     /**
203      * Sets the state the endpoint will be loaded in. The States are 'stopped' and
204      * 'started' (default)
205      * 
206      * @param state
207      */
208     void setInitialState(String state);
209 
210     /**
211      * Determines whether the endpoint should deal with requests as streams
212      * 
213      * @param stream true if the request should be streamed
214      */
215     void setStreaming(boolean stream);
216 }