001 package javax.realtime;
002
003 import java.util.LinkedList;
004 import java.util.Iterator;
005
006 /** An asynchronous event represents something that can happen,
007 * like a light turning red. It can have a set of handlers
008 * associated with it, and when the event occurs, the handler
009 * is scheduled by the scheduler to which it holds a reference.
010 * <p>
011 * A major motivator for this style of building events is that
012 * we expect to have lots of events and lots of event handlers.
013 * An event handler is logically very similar to a thread, but
014 * it is intended to have a much lower cost (in both time and
015 * space) -- assuming that a relatively small number of events
016 * are fired and in the process of being handled at once.
017 * <code>AsyncEvent.fire()</code> deffers from a method call
018 * because the handler has scheduling parameters and is executed
019 * asynchronously.
020 */
021 public class AsyncEvent {
022
023 protected LinkedList handlersList;
024
025 /** Create a new <code>AsyncEvent</code> object. */
026 public AsyncEvent() {
027 handlersList = new LinkedList();
028 }
029
030 /** Add a handler to the set of handlers associated with this
031 * event. An <code>AsyncEvent</code> may have more than one
032 * associated handler.
033 *
034 * @param handler The new handler to add to the list of handlers
035 * already associated with <code>this</code>. If
036 * <code>handler</code> is null then nothing happens.
037 */
038 public void addHandler(AsyncEventHandler handler) {
039 handlersList.add(handler);
040 }
041
042 /** Binds this to an external event, a <i>happening</i>. The meaningful
043 * values of <code>happening</code> are implementation dependent. This
044 * instance of <code>AsyncEvent</code> is considered to have occured
045 * whenever the happening occurs.
046 *
047 * @param hapening An implementation dependent value that binds this
048 * instance of <code>AsyncEvent</code> to a happening.
049 * @throws UnknownHappeningException If the string value is not supported
050 * by the implementation.
051 */
052 public void bindTo(String happening)
053 throws UnknownHappeningException {
054 // TODO
055 }
056
057 /** Create a <code>ReleaseParameters</code> block appropriate
058 * to the timing characteristics of the event. The default is
059 * the most pessimistic: <code>AperiodicParameters</code>.
060 * This is typically called by code that is setting up a
061 * handler for this event that will fill in the parts of the
062 * release parameters for which it has values, e.g., cost.
063 *
064 * @return A new <code>ReleaseParameters</code> object.
065 */
066 public ReleaseParameters createReleaseParameters() {
067 return new AperiodicParameters(null, null, null, null);
068 }
069
070 /** Fire this instance of <code>AsyncEvent</code>. The <code>run()</code>
071 * methods of intances of <code>AsyncEventHandler</code> associated with
072 * this event will be made raedy to run.
073 */
074 public void fire() {
075 for (Iterator it = handlersList.iterator(); it.hasNext(); )
076 ((AsyncEventHandler)it.next()).run();
077 }
078
079 /** Returns true if and only if the handler given as the parameter is
080 * associated with <code>this</code>.
081 *
082 * @param handler The handler to be tested to determine if it is
083 * associated with <code>this</code>.
084 * @return True if the parameter is associated with <code>this</code>.
085 * False, if <code>target</code> is null or the parameter is
086 * not associated with <code>this</code>.
087 */
088 public boolean handledBy(AsyncEventHandler handler) {
089 return (handlersList.contains(handler));
090 }
091
092 /** Remove a handler from the set associated with this event.
093 *
094 * @param handler The handler to be disassociated from <code>this</code>.
095 * If null nothing happens. If not already associated with
096 * this then nothing happens.
097 */
098 public void removeHandler(AsyncEventHandler handler) {
099 handlersList.remove(handler);
100 }
101
102 /** Associate a new handler with this event, removing all existing handlers.
103 *
104 * @param handler The new instance of <code>AsyncEventHandler</code> to be
105 * associated with this. If <code>handler</code> is null then
106 * no handler will be associated with this (i.e., remove all
107 * handlers).
108 */
109 public void setHandler(AsyncEventHandler handler) {
110 handlersList.clear();
111 handlersList.add(handler);
112 }
113
114 /** Removes a binding to an external event, a <i>happening</i>. The meaningful
115 * values of <code>happening</code> are implementation dependent.
116 *
117 * @param happening An implementation dependent value representing some external
118 * event to which this instance of <code>AsyncEvent</code>
119 * is bound.
120 * @throws UnknownHappeningException If this intance of <code>AsyncEvent</code>
121 * is not bound to the given <code>happening</code>
122 * or the given <code>java.lang.String</code> value
123 * is not supported by the implementation.
124 */
125 public void unbindTo(String happening)
126 throws UnknownHappeningException {
127 // TODO
128 }
129 }