001: /*
002: * $Id: MessageAdapter.java 10489 2008-01-23 17:53:38Z 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.transport;
012:
013: import org.mule.api.ExceptionPayload;
014:
015: import java.io.Serializable;
016: import java.util.Map;
017: import java.util.Set;
018:
019: import javax.activation.DataHandler;
020:
021: /**
022: * <code>MessageAdapter</code> provides a common abstraction of different
023: * message implementations provided by different underlying technologies.
024: */
025: public interface MessageAdapter extends Serializable {
026:
027: /**
028: * Adds a map of properties to be associated with this message
029: *
030: * @param properties the properties add to this message
031: */
032: void addProperties(Map properties);
033:
034: /**
035: * Removes all properties on this message
036: */
037: void clearProperties();
038:
039: /**
040: * Gets a property of the message implementation
041: *
042: * @param key the key on which to lookup the property value
043: * @return the property value or null if the property does not exist
044: */
045: Object getProperty(String key);
046:
047: /**
048: * Set a property on the message
049: *
050: * @param key the key on which to associate the value
051: * @param value the property value
052: */
053: void setProperty(String key, Object value);
054:
055: /**
056: * Set a property on the message
057: *
058: * @param key the key on which to associate the value
059: * @param value the property value
060: * @param scope The scope at which to set the property at
061: * @see PropertyScope
062: */
063: void setProperty(String key, Object value, PropertyScope scope);
064:
065: /**
066: * Removes a property on this message
067: *
068: * @param key the property key to remove
069: * @return the removed property value or null if the property did not exist
070: */
071: Object removeProperty(String key);
072:
073: /**
074: * @return all property keys on this message
075: */
076: Set getPropertyNames();
077:
078: /**
079: * @return the current message
080: */
081: Object getPayload();
082:
083: /**
084: * gets the unique identifier for the message. It's up to the implementation to
085: * ensure a unique id
086: *
087: * @return a unique message id. The Id should never be null. If the underlying
088: * transport does not have the notion of a message Id, one shuold be
089: * generated. The generated Id should be a UUID.
090: */
091: String getUniqueId();
092:
093: /**
094: * Gets a property from the message
095: *
096: * @param name the name or key of the property
097: * @param defaultValue a default value if the property doesn't exist in the event
098: * @return the property value or the defaultValue if the property does not exist
099: */
100: Object getProperty(String name, Object defaultValue);
101:
102: /**
103: * Gets an integer property from the message
104: *
105: * @param name the name or key of the property
106: * @param defaultValue a default value if the property doesn't exist in the event
107: * @return the property value or the defaultValue if the property does not exist
108: */
109: int getIntProperty(String name, int defaultValue);
110:
111: /**
112: * Gets a long property from the message
113: *
114: * @param name the name or key of the property
115: * @param defaultValue a default value if the property doesn't exist in the event
116: * @return the property value or the defaultValue if the property does not exist
117: */
118: long getLongProperty(String name, long defaultValue);
119:
120: /**
121: * Gets a double property from the message
122: *
123: * @param name the name or key of the property
124: * @param defaultValue a default value if the property doesn't exist in the event
125: * @return the property value or the defaultValue if the property does not exist
126: */
127: double getDoubleProperty(String name, double defaultValue);
128:
129: /**
130: * Gets a boolean property from the message
131: *
132: * @param name the name or key of the property
133: * @param defaultValue a default value if the property doesn't exist in the event
134: * @return the property value or the defaultValue if the property does not exist
135: */
136: boolean getBooleanProperty(String name, boolean defaultValue);
137:
138: /**
139: * Sets a boolean property on the message
140: *
141: * @param name the property name or key
142: * @param value the property value
143: */
144: void setBooleanProperty(String name, boolean value);
145:
146: /**
147: * Sets a integerproperty on the message
148: *
149: * @param name the property name or key
150: * @param value the property value
151: */
152: void setIntProperty(String name, int value);
153:
154: /**
155: * Sets a long property on the message
156: *
157: * @param name the property name or key
158: * @param value the property value
159: */
160: void setLongProperty(String name, long value);
161:
162: /**
163: * Sets a double property on the message
164: *
165: * @param name the property name or key
166: * @param value the property value
167: */
168: void setDoubleProperty(String name, double value);
169:
170: /**
171: * Gets a String property from the message
172: *
173: * @param name the name or key of the property
174: * @param defaultValue a default value if the property doesn't exist in the event
175: * @return the property value or the defaultValue if the property does not exist
176: */
177: String getStringProperty(String name, String defaultValue);
178:
179: /**
180: * Sets a String property on the message
181: *
182: * @param name the property name or key
183: * @param value the property value
184: */
185: void setStringProperty(String name, String value);
186:
187: /**
188: * Sets a correlationId for this message. The correlation Id can be used by
189: * components in the system to manage message relations <p/> transport protocol.
190: * As such not all messages will support the notion of a correlationId i.e. tcp
191: * or file. In this situation the correlation Id is set as a property of the
192: * message where it's up to developer to keep the association with the message.
193: * For example if the message is serialised to xml the correlationId will be
194: * available in the message.
195: *
196: * @param id the Id reference for this relationship
197: */
198: void setCorrelationId(String id);
199:
200: /**
201: * Sets a correlationId for this message. The correlation Id can be used by
202: * components in the system to manage message relations. <p/> The correlationId
203: * is associated with the message using the underlying transport protocol. As
204: * such not all messages will support the notion of a correlationId i.e. tcp or
205: * file. In this situation the correlation Id is set as a property of the message
206: * where it's up to developer to keep the association with the message. For
207: * example if the message is serialised to xml the correlationId will be
208: * available in the message.
209: *
210: * @return the correlationId for this message or null if one hasn't been set
211: */
212: String getCorrelationId();
213:
214: /**
215: * Gets the sequence or ordering number for this message in the the correlation
216: * group (as defined by the correlationId)
217: *
218: * @return the sequence number or -1 if the sequence is not important
219: */
220: int getCorrelationSequence();
221:
222: /**
223: * Gets the sequence or ordering number for this message in the the correlation
224: * group (as defined by the correlationId)
225: *
226: * @param sequence the sequence number or -1 if the sequence is not important
227: */
228: void setCorrelationSequence(int sequence);
229:
230: /**
231: * Determines how many messages are in the correlation group
232: *
233: * @return total messages in this group or -1 if the size is not known
234: */
235: int getCorrelationGroupSize();
236:
237: /**
238: * Determines how many messages are in the correlation group
239: *
240: * @param size the total messages in this group or -1 if the size is not known
241: */
242: void setCorrelationGroupSize(int size);
243:
244: /**
245: * Sets a replyTo address for this message. This is useful in an asynchronous
246: * environment where the caller doesn't wait for a response and the response
247: * needs to be routed somewhere for further processing. The value of this field
248: * can be any valid endpointUri url.
249: *
250: * @param replyTo the endpointUri url to reply to
251: */
252: void setReplyTo(Object replyTo);
253:
254: /**
255: * Returns a replyTo address for this message. This is useful in an asynchronous
256: * environment where the caller doesn't wait for a response and the response
257: * needs to be routed somewhere for further processing. The value of this field
258: * can be any valid endpointUri url.
259: *
260: * @return the endpointUri url to reply to or null if one has not been set
261: */
262: Object getReplyTo();
263:
264: /**
265: * If an error occurred during the processing of this message this will return a
266: * ErrorPayload that contains the root exception and Mule error code, plus any
267: * other releated info
268: *
269: * @return The exception payload (if any) attached to this message
270: */
271: ExceptionPayload getExceptionPayload();
272:
273: /**
274: * If an error occurs while processing this message, a ErrorPayload is attached
275: * which contains the root exception and Mule error code, plus any other releated
276: * info.
277: *
278: * @param payload The exception payload to attach to this message
279: */
280: void setExceptionPayload(ExceptionPayload payload);
281:
282: /**
283: * Allows for arbitary data attachments to be associated with the Message. These attachements work in the
284: * same way that email attachments work. Attachments can be binary or text
285: * @param name the name to associate with the attachment
286: * @param dataHandler The attachment datahandler to use. This will be used to interract with the attachment data
287: * @throws Exception
288: * @see javax.activation.DataHandler
289: */
290: void addAttachment(String name, DataHandler dataHandler)
291: throws Exception;
292:
293: /**
294: * Remove an attahcment form this message with the specifed name
295: * @param name the name of the attachment to remove. If the attachment does not exist, the request may be ignorred
296: * @throws Exception different messaging systems handle attachments differnetly, as such some will throw an exception
297: * if an attahcment does dot exist.
298: */
299: void removeAttachment(String name) throws Exception;
300:
301: /**
302: * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned
303: * @param name the name of the attachment to retrieve
304: * @return the attachment with the given name or null if the attachment does not exist
305: * @see javax.activation.DataHandler
306: */
307: DataHandler getAttachment(String name);
308:
309: /**
310: * Returns a set of the names of the attachments on this message. If there are no attachments an empty set will be
311: * returned.
312: * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be
313: * returned.
314: */
315: Set getAttachmentNames();
316:
317: /**
318: * Gets the encoding for the current message. For potocols that send encoding
319: * information with the message, this method should be overriden to expose the
320: * transport encoding, otherwise the default encoding in the Mule configuration
321: * will be used.
322: *
323: * @return the encoding for this message. This method must never return null
324: */
325: String getEncoding();
326:
327: /**
328: * Sets the encoding for this message
329: *
330: * @param encoding the encoding to use
331: */
332: void setEncoding(String encoding);
333:
334: /**
335: * Perform any clean up operations on the message resource.
336: * Typically this is used to esure that a message stream is closed
337: */
338: void release();
339: }
|