001: /*
002: * Copyright 2004-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.springframework.webflow.execution;
017:
018: import java.util.EventObject;
019:
020: import org.springframework.util.Assert;
021: import org.springframework.webflow.core.collection.AttributeMap;
022: import org.springframework.webflow.core.collection.CollectionUtils;
023:
024: /**
025: * Signals the occurrence of something an active flow execution should respond
026: * to. Each event has a string id that provides a key for identifying what
027: * happened: e.g "coinInserted", or "pinDropped". Events may have attributes
028: * that provide arbitrary payload data, e.g. "coin.amount=25", or
029: * "pinDropSpeed=25ms".
030: * <p>
031: * As an example, a "submit" event might signal that a Submit button was pressed
032: * in a web browser. A "success" event might signal an action executed
033: * successfully. A "finish" event might signal a subflow ended normally.
034: * <p>
035: * Why is this not an interface? A specific design choice. An event is not a
036: * strategy that defines a generic type or role--it is essentially an immutable
037: * value object. It is expected that specializations of this base class be
038: * "Events" and not part of some other inheritence hierarchy.
039: *
040: * @author Keith Donald
041: * @author Erwin Vervaet
042: * @author Colin Sampaleanu
043: */
044: public final class Event extends EventObject {
045:
046: /**
047: * The event identifier.
048: */
049: private final String id;
050:
051: /**
052: * The time the event occured.
053: */
054: private final long timestamp = System.currentTimeMillis();
055:
056: /**
057: * Additional event attributes that form this event's payload.
058: */
059: private final AttributeMap attributes;
060:
061: /**
062: * Create a new event with the specified <code>id</code> and no payload.
063: * @param source the source of the event (required)
064: * @param id the event identifier (required)
065: */
066: public Event(Object source, String id) {
067: this (source, id, null);
068: }
069:
070: /**
071: * Create a new event with the specified <code>id</code> and payload
072: * attributes.
073: * @param source the source of the event (required)
074: * @param id the event identifier (required)
075: * @param attributes additional event attributes
076: */
077: public Event(Object source, String id, AttributeMap attributes) {
078: super (source);
079: Assert
080: .hasText(
081: id,
082: "The event id is required: please set this event's id to a non-blank string identifier");
083: this .id = id;
084: this .attributes = (attributes != null ? attributes
085: : CollectionUtils.EMPTY_ATTRIBUTE_MAP);
086: }
087:
088: /**
089: * Returns the event identifier.
090: * @return the event id
091: */
092: public String getId() {
093: return id;
094: }
095:
096: /**
097: * Returns the time at which the event occured, represented as the number of
098: * milliseconds since January 1, 1970, 00:00:00 GMT.
099: * @return the timestamp
100: */
101: public long getTimestamp() {
102: return timestamp;
103: }
104:
105: /**
106: * Returns an unmodifiable map storing the attributes of this event. Never
107: * returns <code>null</code>.
108: * @return the event attributes (payload)
109: */
110: public AttributeMap getAttributes() {
111: return attributes;
112: }
113:
114: public String toString() {
115: return getId();
116: }
117: }
|