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