001 package sale;
002
003 import java.io.Serializable;
004 import java.io.IOException;
005
006 import log.*;
007 import users.*;
008
009 import data.Stock;
010 import data.Catalog;
011
012 /**
013 * A context that allows processes to run and access certain functionality.
014 *
015 * <p>A ProcessContext provides {@link SaleProcess processes} with an environment in which they
016 * can work. Although some of the functionality could be accessed directly at the {@link Shop},
017 * some can't, and for the rest the usage of ProcessContexts provides an extra level of flexibility.
018 * It is therefore explicitly recommended that your processes access all of the needed functionality
019 * through their context, except in cases where you want to make sure that a special service is
020 * carried out at Shop level.</p>
021 *
022 * <p>The methods comprising the ProcessContext interface fall into three categories:</p>
023 *
024 * <ol>
025 * <li>Display related methods:
026 * <ul>
027 * <li>{@link #setFormSheet}</li>
028 * <li>{@link #popUpFormSheet}</li>
029 * <li>{@link #setMenuSheet}</li>
030 * <li>{@link #hasUseableDisplay}</li>
031 * </ul>
032 * </li>
033 * <li>Data and service related methods:
034 * <ul>
035 * <li>{@link #log}</li>
036 * <li>{@link #getCurrentUser}</li>
037 * <li>{@link #getStock}</li>
038 * <li>{@link #getCatalog}</li>
039 * </ul>
040 * </li>
041 * <li>Process management methods:
042 * <ul>
043 * <li>{@link #processStarted}</li>
044 * <li>{@link #processFinished}</li>
045 * </ul>
046 * These methods will not be called directly, but rather the Framework will call them as
047 * appropriate.
048 * </li>
049 * </ol>
050 *
051 * @author Steffen Zschaler
052 * @version 2.0 27/05/1999
053 * @since v2.0
054 */
055 public interface ProcessContext extends Serializable {
056
057 // display related methods
058
059 /**
060 * Set a FormSheet for a process.
061 *
062 * <p>The FormSheet will be displayed on the ProcessContext's display for the given process, if there
063 * is one and it is useable. Setting a <code>null</code> FormSheet will remove any FormSheet
064 * currently being displayed.</p>
065 *
066 * @override Always
067 *
068 * @param p the process that wishes to set a FormSheet
069 * @param fs the FormSheet that is to be set.
070 *
071 * @exception InterruptedException if an interrupt occurred while waiting for the FormSheet to be
072 * closed. See {@link Display#setFormSheet Display.setFormSheet} for details.
073 *
074 * @see Display#setFormSheet
075 */
076 public void setFormSheet(SaleProcess p, FormSheet fs) throws InterruptedException;
077
078 /**
079 * Pop up a FormSheet for a process.
080 *
081 * <p>The FormSheet will be popped up on the ProcessContext's display for the given process, if there
082 * is one and it is useable.</p>
083 *
084 * @override Always
085 *
086 * @param p the process that wishes to pop up a FormSheet
087 * @param fs the FormSheet that is to be set.
088 *
089 * @exception InterruptedException if an interrupt occurred while waiting for the FormSheet to be
090 * closed. See {@link Display#popUpFormSheet Display.popUpFormSheet} for details.
091 *
092 * @see Display#popUpFormSheet
093 */
094 public void popUpFormSheet(SaleProcess p, FormSheet fs) throws InterruptedException;
095
096 /**
097 * Set a MenuSheet for a process.
098 *
099 * <p>The MenuSheet will be displayed on the ProcessContext's display for the given process, if there
100 * is one and it is useable. Setting a <code>null</code> MenuSheet will remove any MenuSheet
101 * currently being displayed.</p>
102 *
103 * @override Always
104 *
105 * @param p the process that wishes to set a MenuSheet
106 * @param ms the MenuSheet that is to be set.
107 *
108 * @see Display#setMenuSheet
109 */
110 public void setMenuSheet(SaleProcess p, MenuSheet ms);
111
112 /**
113 * True if the ProcessContext has a useable display for the given process.
114 *
115 * @override Always
116 *
117 * @param p the process whose display is to be checked.
118 *
119 * @see Display#isUseableDisplay
120 */
121 public boolean hasUseableDisplay(SaleProcess p);
122
123 // data and service related methods
124
125 /**
126 * Put an object into the ProcessContext.
127 *
128 * @override Never
129 *
130 * @param sKey object's identifier
131 * @param oData the data object
132 *
133 */
134 public void setProcessData(String sKey, Object oData);
135
136 /**
137 * Get an object from the ProcessContext.
138 *
139 * @override Never
140 *
141 * @param sKey object's key
142 *
143 * @return the object from ProcessContext
144 */
145 public Object getProcessData(String sKey);
146
147 /**
148 * Put an entry into the ProcessContext's log stream for a process.
149 *
150 * @override Always
151 *
152 * @param p the process that wishes to put data into the log stream.
153 * @param la the information that is to be logged.
154 *
155 * @exception IOException if any problems occurred while writing to the log stream.
156 */
157 public void log(SaleProcess p, Loggable la) throws IOException;
158
159 /**
160 * Get the user currently associated with the given process.
161 *
162 * @override Always
163 *
164 * @param p the process that wishes to know its current user.
165 *
166 * @return the current user for the given process.
167 */
168 public User getCurrentUser(SaleProcess p);
169
170 /**
171 * Get a Stock by its name.
172 *
173 * <p>The Stock's name is resolved relative to the ProcessContext, so that the same call can result
174 * in different Stocks in different ProcessContexts.</p>
175 *
176 * @override Always
177 *
178 * @param sName the name of the Stock to be returned.
179 *
180 * @return the Stock that was found for the given name, if any.
181 */
182 public Stock getStock(String sName);
183
184 /**
185 * Get a Catalog by its name.
186 *
187 * <p>The Catalog's name is resolved relative to the ProcessContext, so that the same call can result
188 * in different Catalogs in different ProcessContexts.</p>
189 *
190 * @override Always
191 *
192 * @param sName the name of the Catalog to be returned.
193 *
194 * @return the Catalog that was found for the given name, if any.
195 */
196 public Catalog getCatalog(String sName);
197
198 // process management methods
199
200 /**
201 * Notification that a process was started in this ProcessContext.
202 *
203 * <p>This method is usually not called directly, but rather the Framework calls it as appropriate.</p>
204 *
205 * @override Always
206 *
207 * @param p the process that was started.
208 */
209 public void processStarted(SaleProcess p);
210
211 /**
212 * Notification that a process was finished in this ProcessContext.
213 *
214 * <p>This method is usually not called directly, but rather the Framework calls it as appropriate.</p>
215 *
216 * @override Always
217 *
218 * @param p the process that was finished.
219 */
220 public void processFinished(SaleProcess p);
221 }