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 entry into the ProcessContext's log stream for a process.
127         *
128         * @override Always
129         *
130         * @param p the process that wishes to put data into the log stream.
131         * @param la the information that is to be logged.
132         *
133         * @exception IOException if any problems occurred while writing to the log stream.
134         */
135        public void log(SaleProcess p, Loggable la) throws IOException;
136    
137        /**
138         * Get the user currently associated with the given process.
139         *
140         * @override Always
141         *
142         * @param p the process that wishes to know its current user.
143         *
144         * @return the current user for the given process.
145         */
146        public User getCurrentUser(SaleProcess p);
147    
148        /**
149         * Get a Stock by its name.
150         *
151         * <p>The Stock's name is resolved relative to the ProcessContext, so that the same call can result
152         * in different Stocks in different ProcessContexts.</p>
153         *
154         * @override Always
155         *
156         * @param sName the name of the Stock to be returned.
157         *
158         * @return the Stock that was found for the given name, if any.
159         */
160        public Stock getStock(String sName);
161    
162        /**
163         * Get a Catalog by its name.
164         *
165         * <p>The Catalog's name is resolved relative to the ProcessContext, so that the same call can result
166         * in different Catalogs in different ProcessContexts.</p>
167         *
168         * @override Always
169         *
170         * @param sName the name of the Catalog to be returned.
171         *
172         * @return the Catalog that was found for the given name, if any.
173         */
174        public Catalog getCatalog(String sName);
175    
176        // process management methods
177    
178        /**
179         * Notification that a process was started in this ProcessContext.
180         *
181         * <p>This method is usually not called directly, but rather the Framework calls it as appropriate.</p>
182         *
183         * @override Always
184         *
185         * @param p the process that was started.
186         */
187        public void processStarted(SaleProcess p);
188    
189        /**
190         * Notification that a process was finished in this ProcessContext.
191         *
192         * <p>This method is usually not called directly, but rather the Framework calls it as appropriate.</p>
193         *
194         * @override Always
195         *
196         * @param p the process that was finished.
197         */
198        public void processFinished(SaleProcess p);
199    }