EggContext


1   /*
2    * Copyright (c) 2004, Bruce Lowery
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions are met:
7    *
8    *    - Redistributions of source code must retain the above copyright notice,
9    *      this list of conditions and the following disclaimer.
10   *    - Redistributions in binary form must reproduce the above copyright
11   *      notice, this list of conditions and the following disclaimer in the
12   *      documentation and/or other materials provided with the distribution.
13   *    - Neither the name of GOSSIP nor the names of its contributors may be used
14   *      to endorse or promote products derived from this software without
15   *      specific prior written permission.
16   *
17   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20   * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
21   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27   * POSSIBILITY OF SUCH DAMAGE.
28   */
29  package jegg;
30  
31  import jegg.impl.Dispatcher;
32  import jegg.impl.Priority;
33  import jegg.impl.Property;
34  import jegg.timer.Timer;
35  
36  /**
37   * The execution context of an egg.  This class mainly provides a set of
38   * methods that are useful during the handling of a message.
39   */
40  public interface EggContext
41  {
42      /**
43       * Return a property configured on this egg in the application 
44       * descriptor.
45       * @param key the name of the property.
46       * @return the value of the property or null if the property can't be found.
47       */
48      public String   getProperty(String   key);
49  
50      /**
51       * Return a property configured on this egg in the application descriptor.
52       * If the property can't be found, then a specified default will be
53       * returned.
54       * 
55       * @param key the name of the property.
56       * @param defValue the value to return if the property can't be found.
57       * @return the value of the property or the specified default.
58       */
59      public String   getProperty(String   key, String   defValue);
60  
61      /**
62       * Return all of the properties configured on this egg in the 
63       * application descriptor.
64       * @return non-null array of properties that may be empty.
65       */
66      public Property[] getProperties();
67  
68      /**
69       * Bind this egg to the specified port which belongs to another egg.
70       * After the binding, this egg will receive all messages that the
71       * other egg broadcasts.
72       * @param p the port to bind to in order to receive all broadcast
73       * message from the egg that owns the port.
74       */
75      public void bindToPort(final Port p);
76  
77      /**
78       * Create a message at the default priority that is ready to be directly 
79       * written to a message port. 
80       * Usually it is not necessary to call this method since the 
81       * <code>send</code> method accepts the object message to send and
82       * internally wraps it in a message instance.
83       * @param m the application message to wrap.
84       * @return the wrapped application message.
85       */
86      public Message createMessage(final Object   m);
87  
88      /**
89       * Create a message at the specified priority that is ready to be directly 
90       * written to a message port. 
91       * 
92       * @param m the application message to wrap.
93       * @param p the priority to assign to the message.
94       * @return the wrapped application message.
95       */
96      public Message createMessage(final Object   m, final Priority p);
97  
98      /**
99       * Create a timer that will periodically send timeout messages to this egg.
100      * @param interval_msec the interval, in milliseconds, at which the 
101      * timeout messages should be sent.
102      * @param delay_msec the initial delay, in milliseconds, before the first timeout should
103      * be sent.
104      * @return
105      */
106     public Timer createRepeatingTimer(final long interval_msec,
107             final long delay_msec);
108 
109     /**
110      * Create a timer that will send a single timeout message to this egg.
111      * @param delay_msec the initial delay, in milliseconds, before the timeout is sent.
112      * @return
113      */
114     public Timer createSingleShotTimer(final long delay_msec);
115 
116     /**
117      * Return the message wrapper of the application message that is currently
118      * being handled.
119      * @return the current message or null if a message is not being handled.
120      */
121     public Message getCurrentMessage();
122 
123     /**
124      * Return the dispatcher that this egg is assigned to.
125      * @return the dispatcher for this egg.
126      */
127     public Dispatcher getDispatcher();
128 
129     /**
130      * Return the port of the egg that sent the application message that is
131      * currently being handled.
132      * @return the sending egg's message port.
133      */
134     public Port getFromPort();
135 
136     /**
137      * Return the ID of this egg as assigned to it in the application descriptor.
138      * @return this egg's message ID.
139      */
140     public Object   getId();
141 
142     /**
143      * Return the set of message types that this egg recognizes.  Each class
144      * object represents a handle method on this egg that takes that type
145      * as an argument.
146      * @return array of class objects, one for each message type that this
147      * egg recognizes.
148      */
149     public Class  [] getInterface();
150 
151     /**
152      * Return this egg's message port.
153      * @return this egg's message port.
154      */
155     public Port getPort();
156 
157     /**
158      * Publish this egg's message port in the JEgg framework registry.
159      * @param n the name that the message port should be published under.
160      */
161     public void publishPort(final String   n);
162 
163     /**
164      * Request a lookup of a message port in the JEgg framework registry.
165      * If found, the port will be delivered to the handle method that takes
166      * a port instance.  If the port is not registered at the time that the
167      * port registry receives this request, the registry will retain the
168      * request information and notify the requesting egg once the port has
169      * been registered.
170      * @param n the name that the requested port is expected to be registered
171      * under.
172      */
173     public void requestPort(final String   n);
174 
175     /**
176      * Send a message to the egg that sent the current message.
177      * The message will be sent with a <i>medium</i> priority
178      * level assigned to it.
179      * 
180      * @param message the message to send to the sending egg.
181      */
182     public void respond(final Object   message);
183 
184     /**
185      * Send a message to the egg that sent the current message.
186      * The message will be sent with the specified priority
187      * level assigned to it.
188      * 
189      * @param message the message to send to the sending egg.
190      * @param priority the priority to assign to the message.
191      */
192     public void respond(final Object   message, final Priority priority);
193 
194     /**
195      * Send a message to the egg that the specified port
196      * belongs to.  This method is useful when a message
197      * response has to be delayed until later (so the port
198      * is saved for use later). The message will be sent
199      * with a medium priority level assigned to it.
200      * 
201      * @param port the port to send the message on.
202      * @param message the message to send to the egg that
203      * the specified port belongs to.
204      */
205     public void respond(final Port port, final Object   message);
206 
207     /**
208      * Send a message to the egg that the specified port
209      * belongs to.  This method is useful when a message
210      * response has to be delayed until later (so the port
211      * is saved for use later). The message will be sent
212      * with the specified priority level assigned to it.
213      * 
214      * @param port the port to send the message on.
215      * @param message the message to send to the egg that
216      * the specified port belongs to.
217      * @param priority the message's priority assignment.
218      */
219     public void respond(final Port port, final Object   message,
220             final Priority priority);
221 
222     /**
223      * Broadcast a message to all eggs that have bound to this egg's port
224      * (see {@link #bindToPort(Port) bindToPort}).
225      * 
226      * @param message the message to send.
227      */
228     public void send(final Object   msg);
229 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags