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 -> admin@mycompany.com</li> 50 * <li>jms -> shipping.orders.topic</li> 51 * <li>sms -> +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 }