001: /*
002: * $Id: ImmutableEndpoint.java 11311 2008-03-10 20:15:57Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api.endpoint;
012:
013: import org.mule.api.MuleContext;
014: import org.mule.api.routing.filter.Filter;
015: import org.mule.api.security.EndpointSecurityFilter;
016: import org.mule.api.transaction.TransactionConfig;
017: import org.mule.api.transport.ConnectionStrategy;
018: import org.mule.api.transport.Connector;
019:
020: import java.io.Serializable;
021: import java.util.List;
022: import java.util.Map;
023:
024: /**
025: * <code>ImmutableEndpoint</code> describes a Message endpoint where data is
026: * sent or received. An Enpoint is an Resource address (EndpointUri), with associated
027: * transformation, transaction and filtering rules.
028: */
029: public interface ImmutableEndpoint extends Serializable {
030:
031: public static final String INITIAL_STATE_STARTED = "started";
032: public static final String INITIAL_STATE_STOPPED = "stopped";
033:
034: /**
035: * This specifess the communication endpointUri. This will have a different format
036: * depending on the transport protocol being used i.e.
037: * <ul>
038: * <li>smtp -> admin@mycompany.com</li>
039: * <li>jms -> shipping.orders.topic</li>
040: * <li>sms -> +447910010010</li>
041: * </ul>
042: * <p/> if an endpointUri is not specifed it will be assumed that it will be
043: * determined at run-time by the calling application. The endpointUri can be
044: * aliteral endpointUri such as an email address or it can be a logical name for
045: * an endpointUri as long as it is declared in a <i>message-endpointUri</i>
046: * block. When the message-provider is created the endpointUri is first lookup in
047: * the endpointUri registry and if nothing is returned the endpointUri value
048: * itself is used.
049: *
050: * @return the endpointUri on which the endpoint sends or receives data
051: */
052: EndpointURI getEndpointURI();
053:
054: /**
055: * Decides the encoding to be used for events received by this endpoint
056: *
057: * @return the encoding set on the endpoint or null if no codin has been
058: * specified
059: */
060: String getEncoding();
061:
062: /**
063: * The endpoint that will be used to send the message on. It is important that
064: * the endpointUri and the connection correlate i.e. if your endpointUri is a jms
065: * queue your connection must be a JMS endpoint.
066: *
067: * @return the endpoint associated with the endpoint
068: */
069: Connector getConnector();
070:
071: /**
072: * The name is the identifier for the endpoint
073: *
074: * @return the endpoint name
075: */
076: String getName();
077:
078: /**
079: * Transformers are responsible for transforming data when it is received or
080: * sent by the UMO (depending on whether this endpoint is a receiver or not). A
081: * tranformation for an inbound event can be forced by the user by calling the
082: * inbound event.getTransformedMessage(). A tranformation for an outbound event
083: * is called or when the UMO dispatchEvent() or sendEvent() methods are called.
084: * If an endpoint has no transformers an empty list is returned.
085: *
086: * @return the transformers to use when receiving or sending data
087: */
088: List getTransformers();
089:
090: /**
091: * The transformers used when a response is returned from invoking this endpoint.
092: * If an endpoint has no response transformers an empty list is returned.
093: * @return the transformer to use when receiving the response data
094: */
095: List getResponseTransformers();
096:
097: /**
098: * Returns any properties set on this endpoint
099: *
100: * @return a map of properties for this endpoint
101: */
102: Map getProperties();
103:
104: /**
105: * Retrieves a property set on the endpoint
106: *
107: * @param key the name of the property
108: * @return the property value or null if it does not exist
109: */
110: Object getProperty(Object key);
111:
112: /**
113: * The transport protocol name that the message endpoint communicates over. i.e.
114: * jms, sms, smtp etc. The protocol must match that of the associated endpoint
115: *
116: * @return the protocol name
117: */
118: String getProtocol();
119:
120: /**
121: * @return true if this endpoint is read-only and none of it's properties can
122: * change. Global endpoints should be read-only so that unexpected
123: * behaviour is avoided.
124: */
125: boolean isReadOnly();
126:
127: /**
128: * Returns the transaction configuration for this endpoint
129: *
130: * @return the transaction configuration for this endpoint or null if the
131: * endpoint is not transactional
132: */
133: TransactionConfig getTransactionConfig();
134:
135: /**
136: * The filter to apply to incoming messages. Only applies when the endpoint
137: * endpointUri is a receiver
138: *
139: * @return the Filter to use or null if one is not set
140: */
141: Filter getFilter();
142:
143: /**
144: * If a filter is configured on this endpoint, this property will determine if
145: * message that are not excepted by the filter are deleted
146: *
147: * @return true if message should be deleted, false otherwise
148: */
149: boolean isDeleteUnacceptedMessages();
150:
151: /**
152: * Returns an EndpointSecurityFilter for this endpoint. If one is not set,
153: * there will be no authentication on events sent via this endpoint
154: *
155: * @return EndpointSecurityFilter responsible for authenticating message flow
156: * via this endpoint.
157: * @see EndpointSecurityFilter
158: */
159: EndpointSecurityFilter getSecurityFilter();
160:
161: /**
162: * Determines if requests originating from this endpoint should be synchronous
163: * i.e. execute in a single thread and possibly return an result. This property
164: * is only used when the endpoint is of type 'receiver'
165: *
166: * @return whether requests on this endpoint should execute in a single thread.
167: * This property is only used when the endpoint is of type 'receiver'
168: */
169: boolean isSynchronous();
170:
171: /**
172: * For certain providers that support the notion of a backchannel such as sockets
173: * (outputStream) or Jms (ReplyTo) Mule can automatically wait for a response
174: * from a backchannel when dispatching over these protocols. This is different
175: * for synchronous as synchronous behavior only applies to in
176: *
177: */
178: boolean isRemoteSync();
179:
180: /**
181: * The timeout value for remoteSync invocations
182: *
183: * @return the timeout in milliseconds
184: */
185: int getRemoteSyncTimeout();
186:
187: /**
188: * Sets the state the endpoint will be loaded in. The States are 'stopped' and
189: * 'started' (default)
190: *
191: * @return the endpoint starting state
192: */
193: String getInitialState();
194:
195: MuleContext getMuleContext();
196:
197: /**
198: * Returns the connection strategy this endpoint should use when connecting to the underlying resource
199: * @return the connection strategy this endpoint should use when connecting to the underlying resource
200: */
201: ConnectionStrategy getConnectionStrategy();
202: }
|