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 }