001    /*
002     * Copyright 1999-2001,2004 The Apache Software Foundation.
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    
017    package org.apache.commons.workflow;
018    
019    
020    import java.util.Map;
021    
022    
023    /**
024     * <p>A <strong>Scope</strong> is a collection of arbitrary Java objects,
025     * keyed by String-valued names.  Specialized workflow implementations
026     * will register their own <code>Scope</code> implementations to connect
027     * the workflow engine processing to their own execution environments.
028     * For example, a web layer implementation would most likely adapt
029     * Scopes to the request attributes, session attributes, and servlet
030     * context attributes provided by the Servlet API.</p>
031     *
032     * <p>A Scope implements the API contracts of <code>java.util.Map</code>
033     * with the following additional rules:</p>
034     * <ul>
035     * <li>Keys must be of the <code>java.lang.String</code></li>
036     * <li>Null keys are not allowed</li>
037     * <li>Null beans are not allowed</li>
038     * </ul>
039     *
040     * @version $Revision: 155475 $ $Date: 2005-02-26 13:31:11 +0000 (Sat, 26 Feb 2005) $
041     * @author Craig R. McClanahan
042     */
043    
044    public interface Scope extends Map {
045    
046    
047        // ------------------------------------------------------------ Map Methods
048    
049    
050        /**
051         * Remove all beans from this Map and call <code>scopeCleared() on
052         * all registered <code>ScopeListeners</code>.
053         */
054        public void clear();
055    
056    
057        /**
058         * Add the specified bean, associated with the specified key, to this
059         * scope and replace any previous bean associated with this key.  If
060         * the bean was added, call <code>beanAdded()</code> on all registered
061         * listeners after the add is done.  If an old bean was replaced,
062         * call <code>beanReplaced()</code> (passing the old value in the event)
063         * on all registered <code>ScopeListeners</code> after the removal
064         * is done.  If a bean was replaced, the old value is also returned;
065         * otherwise <code>null</code> is returned.
066         *
067         * @param key Key with which the new value should be associated
068         *  (cannot be null)
069         * @param bean Bean to be associated with this key (cannot be null)
070         *
071         * @exception IllegalArgumentException if <code>key</code> or
072         *  <code>bean</code> is null
073         */
074        public Object put(String key, Object bean);
075    
076    
077        /**
078         * Remove the bean associated with the specified key (if any).  If such
079         * a bean is found and removed, call <code>beanRemoved()</code> on all
080         * registered <code>ScopeListeners</code> after the removal is done.
081         * Return the old value (if any); otherwise return <code>null</code>.
082         *
083         * @param key Key of the bean to remove (cannot be null)
084         *
085         * @exception IllegalArgumentException if <code>key</code> is null
086         */
087        public Object remove(String key);
088    
089    
090        // ------------------------------------------------- Event Listener Methods
091    
092    
093        /**
094         * Add a listener that is notified each time beans are added,
095         * replaced, or removed in this scope.
096         *
097         * @param listener The ScopeListener to be added
098         */
099        public void addScopeListener(ScopeListener listener);
100    
101    
102        /**
103         * Remove a listener that is notified each time beans are added,
104         * replaced, or removed in this scope.
105         *
106         * @param listener The ScopeListener to be removed
107         */
108        public void removeScopeListener(ScopeListener listener);
109    
110    
111    }