1 /* 2 * $Id: ImmutableEndpoint.java 12269 2008-07-10 04:19:03Z dfeist $ 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.api.endpoint; 12 13 import org.mule.api.MuleContext; 14 import org.mule.api.routing.filter.Filter; 15 import org.mule.api.security.EndpointSecurityFilter; 16 import org.mule.api.transaction.TransactionConfig; 17 import org.mule.api.transport.ConnectionStrategy; 18 import org.mule.api.transport.Connector; 19 20 import java.io.Serializable; 21 import java.util.List; 22 import java.util.Map; 23 24 /** 25 * <code>ImmutableEndpoint</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 ImmutableEndpoint extends Serializable 30 { 31 32 String INITIAL_STATE_STARTED = "started"; 33 String INITIAL_STATE_STOPPED = "stopped"; 34 35 /** 36 * This specifess the communication endpointUri. This will have a different format 37 * depending on the transport protocol being used i.e. 38 * <ul> 39 * <li>smtp -> admin@mycompany.com</li> 40 * <li>jms -> shipping.orders.topic</li> 41 * <li>sms -> +447910010010</li> 42 * </ul> 43 * <p/> if an endpointUri is not specifed it will be assumed that it will be 44 * determined at run-time by the calling application. The endpointUri can be 45 * aliteral endpointUri such as an email address or it can be a logical name for 46 * an endpointUri as long as it is declared in a <i>message-endpointUri</i> 47 * block. When the message-provider is created the endpointUri is first lookup in 48 * the endpointUri registry and if nothing is returned the endpointUri value 49 * itself is used. 50 * 51 * @return the endpointUri on which the endpoint sends or receives data 52 */ 53 EndpointURI getEndpointURI(); 54 55 /** 56 * Decides the encoding to be used for events received by this endpoint 57 * 58 * @return the encoding set on the endpoint or null if no codin has been 59 * specified 60 */ 61 String getEncoding(); 62 63 /** 64 * The endpoint that will be used to send the message on. It is important that 65 * the endpointUri and the connection correlate i.e. if your endpointUri is a jms 66 * queue your connection must be a JMS endpoint. 67 * 68 * @return the endpoint associated with the endpoint 69 */ 70 Connector getConnector(); 71 72 /** 73 * The name is the identifier for the endpoint 74 * 75 * @return the endpoint name 76 */ 77 String getName(); 78 79 /** 80 * Transformers are responsible for transforming data when it is received or 81 * sent by the UMO (depending on whether this endpoint is a receiver or not). A 82 * tranformation for an inbound event can be forced by the user by calling the 83 * inbound event.getTransformedMessage(). A tranformation for an outbound event 84 * is called or when the UMO dispatchEvent() or sendEvent() methods are called. 85 * If an endpoint has no transformers an empty list is returned. 86 * 87 * @return the transformers to use when receiving or sending data 88 */ 89 List getTransformers(); 90 91 /** 92 * The transformers used when a response is returned from invoking this endpoint. 93 * If an endpoint has no response transformers an empty list is returned. 94 * @return the transformer to use when receiving the response data 95 */ 96 List getResponseTransformers(); 97 98 /** 99 * Returns any properties set on this endpoint 100 * 101 * @return a map of properties for this endpoint 102 */ 103 Map getProperties(); 104 105 /** 106 * Retrieves a property set on the endpoint 107 * 108 * @param key the name of the property 109 * @return the property value or null if it does not exist 110 */ 111 Object getProperty(Object key); 112 113 /** 114 * The transport protocol name that the message endpoint communicates over. i.e. 115 * jms, sms, smtp etc. The protocol must match that of the associated endpoint 116 * 117 * @return the protocol name 118 */ 119 String getProtocol(); 120 121 /** 122 * @return true if this endpoint is read-only and none of it's properties can 123 * change. Global endpoints should be read-only so that unexpected 124 * behaviour is avoided. 125 */ 126 boolean isReadOnly(); 127 128 /** 129 * Returns the transaction configuration for this endpoint 130 * 131 * @return the transaction configuration for this endpoint or null if the 132 * endpoint is not transactional 133 */ 134 TransactionConfig getTransactionConfig(); 135 136 /** 137 * The filter to apply to incoming messages. Only applies when the endpoint 138 * endpointUri is a receiver 139 * 140 * @return the Filter to use or null if one is not set 141 */ 142 Filter getFilter(); 143 144 /** 145 * If a filter is configured on this endpoint, this property will determine if 146 * message that are not excepted by the filter are deleted 147 * 148 * @return true if message should be deleted, false otherwise 149 */ 150 boolean isDeleteUnacceptedMessages(); 151 152 /** 153 * Returns an EndpointSecurityFilter for this endpoint. If one is not set, 154 * there will be no authentication on events sent via this endpoint 155 * 156 * @return EndpointSecurityFilter responsible for authenticating message flow 157 * via this endpoint. 158 * @see EndpointSecurityFilter 159 */ 160 EndpointSecurityFilter getSecurityFilter(); 161 162 /** 163 * Determines if requests originating from this endpoint should be synchronous 164 * i.e. execute in a single thread and possibly return an result. This property 165 * is only used when the endpoint is of type 'receiver' 166 * 167 * @return whether requests on this endpoint should execute in a single thread. 168 * This property is only used when the endpoint is of type 'receiver' 169 */ 170 boolean isSynchronous(); 171 172 /** 173 * For certain providers that support the notion of a backchannel such as sockets 174 * (outputStream) or Jms (ReplyTo) Mule can automatically wait for a response 175 * from a backchannel when dispatching over these protocols. This is different 176 * for synchronous as synchronous behavior only applies to in 177 * 178 */ 179 boolean isRemoteSync(); 180 181 /** 182 * The timeout value for remoteSync invocations 183 * 184 * @return the timeout in milliseconds 185 */ 186 int getRemoteSyncTimeout(); 187 188 /** 189 * Sets the state the endpoint will be loaded in. The States are 'stopped' and 190 * 'started' (default) 191 * 192 * @return the endpoint starting state 193 */ 194 String getInitialState(); 195 196 MuleContext getMuleContext(); 197 198 /** 199 * Returns the connection strategy this endpoint should use when connecting to the underlying resource 200 * @return the connection strategy this endpoint should use when connecting to the underlying resource 201 */ 202 ConnectionStrategy getConnectionStrategy(); 203 }