Add Message, MessageChannel and refactor stomp support

spring-context/src/main/java/org/springframework/messaging/GenericMessage.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging;
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * Base Message class defining common properties such as id, payload, and headers.
+ * Once created this object is immutable.
+ *
+ * @author Mark Fisher
+ * @since 4.0
+ */
+public class GenericMessage<T> implements Message<T>, Serializable {
+
+	private static final long serialVersionUID = -9004496725833093406L;
+
+	private final T payload;
+
+	private final MessageHeaders headers;
+
+
+	/**
+	 * Create a new message with the given payload.
+	 *
+	 * @param payload the message payload
+	 */
+	public GenericMessage(T payload) {
+		this(payload, null);
+	}
+
+	/**
+	 * Create a new message with the given payload. The provided map
+	 * will be used to populate the message headers
+	 *
+	 * @param payload the message payload
+	 * @param headers message headers
+	 * @see MessageHeaders
+	 */
+	public GenericMessage(T payload, Map<String, Object> headers) {
+		Assert.notNull(payload, "payload must not be null");
+		if (headers == null) {
+			headers = new HashMap<String, Object>();
+		}
+		else {
+			headers = new HashMap<String, Object>(headers);
+		}
+		this.headers = new MessageHeaders(headers);
+		this.payload = payload;
+	}
+
+
+	public MessageHeaders getHeaders() {
+		return this.headers;
+	}
+
+	public T getPayload() {
+		return this.payload;
+	}
+
+	public String toString() {
+		return "[Payload=" + this.payload + "][Headers=" + this.headers + "]";
+	}
+
+	public int hashCode() {
+		return this.headers.hashCode() * 23 + ObjectUtils.nullSafeHashCode(this.payload);
+	}
+
+	public boolean equals(Object obj) {
+		if (this == obj) {
+			return true;
+		}
+		if (obj != null && obj instanceof GenericMessage<?>) {
+			GenericMessage<?> other = (GenericMessage<?>) obj;
+			if (!this.headers.getId().equals(other.headers.getId())) {
+				return false;
+			}
+			return this.headers.equals(other.headers)
+					&& this.payload.equals(other.payload);
+		}
+		return false;
+	}
+
+}

spring-context/src/main/java/org/springframework/messaging/Message.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging;
+
+/**
+ * A generic message representation with headers and body.
+ *
+ * @author Mark Fisher
+ * @author Arjen Poutsma
+ * @since 4.0
+ */
+public interface Message<T> {
+
+	MessageHeaders getHeaders();
+
+	T getPayload();
+
+}

spring-context/src/main/java/org/springframework/messaging/MessageChannel.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging;
+
+/**
+ * Base channel interface defining common behavior for sending messages.
+ *
+ * @author Mark Fisher
+ * @since 4.0
+ */
+public interface MessageChannel {
+
+	/**
+	 * Send a {@link Message} to this channel. May throw a RuntimeException for
+	 * non-recoverable errors. Otherwise, if the Message cannot be sent for a
+	 * non-fatal reason this method will return 'false', and if the Message is
+	 * sent successfully, it will return 'true'.
+	 *
+	 * <p>Depending on the implementation, this method may block indefinitely.
+	 * To provide a maximum wait time, use {@link #send(Message, long)}.
+	 *
+	 * @param message the {@link Message} to send
+	 *
+	 * @return whether or not the Message has been sent successfully
+	 */
+	boolean send(Message<?> message);
+
+}

spring-context/src/main/java/org/springframework/messaging/MessageHeaders.java

@@ -0,0 +1,248 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging;
+
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+/**
+ * The headers for a {@link Message}.<br>
+ * IMPORTANT: MessageHeaders are immutable. Any mutating operation (e.g., put(..), putAll(..) etc.)
+ * will result in {@link UnsupportedOperationException}
+ * <p>
+ * TODO: update javadoc
+ *
+ * <p>To create MessageHeaders instance use fluent MessageBuilder API
+ * <pre>
+ * MessageBuilder.withPayload("foo").setHeader("key1", "value1").setHeader("key2", "value2");
+ * </pre>
+ * or create an instance of GenericMessage passing payload as {@link Object} and headers as a regular {@link Map}
+ * <pre>
+ * Map headers = new HashMap();
+ * headers.put("key1", "value1");
+ * headers.put("key2", "value2");
+ * new GenericMessage("foo", headers);
+ * </pre>
+ *
+ * @author Arjen Poutsma
+ * @author Mark Fisher
+ * @author Oleg Zhurakousky
+ * @author Gary Russell
+ * @since 4.0
+ */
+public final class MessageHeaders implements Map<String, Object>, Serializable {
+
+	private static final long serialVersionUID = 8946067357652612145L;
+
+	private static final Log logger = LogFactory.getLog(MessageHeaders.class);
+
+	private static volatile IdGenerator idGenerator = null;
+
+	/**
+	 * The key for the Message ID. This is an automatically generated UUID and
+	 * should never be explicitly set in the header map <b>except</b> in the
+	 * case of Message deserialization where the serialized Message's generated
+	 * UUID is being restored.
+	 */
+	public static final String ID = "id";
+
+	public static final String TIMESTAMP = "timestamp";
+
+	public static final String REPLY_CHANNEL = "replyChannel";
+
+	public static final String ERROR_CHANNEL = "errorChannel";
+
+	public static final String CONTENT_TYPE = "content-type";
+
+	// DESTINATION ?
+
+	public static final List<String> HEADER_NAMES =
+			Arrays.asList(ID, TIMESTAMP, REPLY_CHANNEL, ERROR_CHANNEL, CONTENT_TYPE);
+
+
+	private final Map<String, Object> headers;
+
+
+	public MessageHeaders(Map<String, Object> headers) {
+		this.headers = (headers != null) ? new HashMap<String, Object>(headers) : new HashMap<String, Object>();
+		if (MessageHeaders.idGenerator == null){
+			this.headers.put(ID, UUID.randomUUID());
+		}
+		else {
+			this.headers.put(ID, MessageHeaders.idGenerator.generateId());
+		}
+
+		this.headers.put(TIMESTAMP, new Long(System.currentTimeMillis()));
+	}
+
+	public UUID getId() {
+		return this.get(ID, UUID.class);
+	}
+
+	public Long getTimestamp() {
+		return this.get(TIMESTAMP, Long.class);
+	}
+
+	public Object getReplyChannel() {
+		return this.get(REPLY_CHANNEL);
+	}
+
+	public Object getErrorChannel() {
+		return this.get(ERROR_CHANNEL);
+	}
+
+	@SuppressWarnings("unchecked")
+	public <T> T get(Object key, Class<T> type) {
+		Object value = this.headers.get(key);
+		if (value == null) {
+			return null;
+		}
+		if (!type.isAssignableFrom(value.getClass())) {
+			throw new IllegalArgumentException("Incorrect type specified for header '" + key + "'. Expected [" + type
+					+ "] but actual type is [" + value.getClass() + "]");
+		}
+		return (T) value;
+	}
+
+	@Override
+	public int hashCode() {
+		return this.headers.hashCode();
+	}
+
+	@Override
+	public boolean equals(Object object) {
+		if (this == object) {
+			return true;
+		}
+		if (object != null && object instanceof MessageHeaders) {
+			MessageHeaders other = (MessageHeaders) object;
+			return this.headers.equals(other.headers);
+		}
+		return false;
+	}
+
+	@Override
+	public String toString() {
+		return this.headers.toString();
+	}
+
+	/*
+	 * Map implementation
+	 */
+
+	public boolean containsKey(Object key) {
+		return this.headers.containsKey(key);
+	}
+
+	public boolean containsValue(Object value) {
+		return this.headers.containsValue(value);
+	}
+
+	public Set<Map.Entry<String, Object>> entrySet() {
+		return Collections.unmodifiableSet(this.headers.entrySet());
+	}
+
+	public Object get(Object key) {
+		return this.headers.get(key);
+	}
+
+	public boolean isEmpty() {
+		return this.headers.isEmpty();
+	}
+
+	public Set<String> keySet() {
+		return Collections.unmodifiableSet(this.headers.keySet());
+	}
+
+	public int size() {
+		return this.headers.size();
+	}
+
+	public Collection<Object> values() {
+		return Collections.unmodifiableCollection(this.headers.values());
+	}
+
+	// Unsupported operations
+
+	/**
+	 * Since MessageHeaders are immutable the call to this method will result in {@link UnsupportedOperationException}
+	 */
+	public Object put(String key, Object value) {
+		throw new UnsupportedOperationException("MessageHeaders is immutable.");
+	}
+
+	/**
+	 * Since MessageHeaders are immutable the call to this method will result in {@link UnsupportedOperationException}
+	 */
+	public void putAll(Map<? extends String, ? extends Object> t) {
+		throw new UnsupportedOperationException("MessageHeaders is immutable.");
+	}
+
+	/**
+	 * Since MessageHeaders are immutable the call to this method will result in {@link UnsupportedOperationException}
+	 */
+	public Object remove(Object key) {
+		throw new UnsupportedOperationException("MessageHeaders is immutable.");
+	}
+
+	/**
+	 * Since MessageHeaders are immutable the call to this method will result in {@link UnsupportedOperationException}
+	 */
+	public void clear() {
+		throw new UnsupportedOperationException("MessageHeaders is immutable.");
+	}
+
+	// Serialization methods
+
+	private void writeObject(ObjectOutputStream out) throws IOException {
+		List<String> keysToRemove = new ArrayList<String>();
+		for (Map.Entry<String, Object> entry : this.headers.entrySet()) {
+			if (!(entry.getValue() instanceof Serializable)) {
+				keysToRemove.add(entry.getKey());
+			}
+		}
+		for (String key : keysToRemove) {
+			if (logger.isInfoEnabled()) {
+				logger.info("removing non-serializable header: " + key);
+			}
+			this.headers.remove(key);
+		}
+		out.defaultWriteObject();
+	}
+
+	private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
+		in.defaultReadObject();
+	}
+
+	public static interface IdGenerator {
+		UUID generateId();
+	}
+}

spring-context/src/main/java/org/springframework/messaging/MessagingException.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging;
+
+/**
+ * The base exception for any failures related to messaging.
+ *
+ * @author Mark Fisher
+ * @author Gary Russell
+ * @since 4.0
+ */
+@SuppressWarnings("serial")
+public class MessagingException extends RuntimeException {
+
+	private volatile Message<?> failedMessage;
+
+
+	public MessagingException(Message<?> message) {
+		super();
+		this.failedMessage = message;
+	}
+
+	public MessagingException(String description) {
+		super(description);
+		this.failedMessage = null;
+	}
+
+	public MessagingException(String description, Throwable cause) {
+		super(description, cause);
+		this.failedMessage = null;
+	}
+
+	public MessagingException(Message<?> message, String description) {
+		super(description);
+		this.failedMessage = message;
+	}
+
+	public MessagingException(Message<?> message, Throwable cause) {
+		super(cause);
+		this.failedMessage = message;
+	}
+
+	public MessagingException(Message<?> message, String description, Throwable cause) {
+		super(description, cause);
+		this.failedMessage = message;
+	}
+
+	public Message<?> getFailedMessage() {
+		return this.failedMessage;
+	}
+
+	public void setFailedMessage(Message<?> message) {
+		this.failedMessage = message;
+	}
+
+}

spring-context/src/main/java/org/springframework/messaging/annotation/MessageMapping.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2002-2013 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.messaging.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+
+/**
+ * @author Rossen Stoyanchev
+ * @since 4.0
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface MessageMapping {
+
+	/**
+	 * Destination values for the message.
+	 */
+	String[] value() default {};
+
+}

spring-context/src/main/java/org/springframework/messaging/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Generic support for working with messaging APIs and protocols.
+ */
+package org.springframework.messaging;