View Javadoc

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