View Javadoc
1   package org.codehaus.plexus.context;
2   
3   import java.util.Map;
4   
5   /*
6    * Copyright 2001-2006 Codehaus Foundation.
7    *
8    * Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *      http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  
21  /**
22   * Context is a Map of arbitrary data associated with the container.
23   */
24  public interface Context {
25      /**
26       * Returns true if this context contains a value for the specified key.
27       *
28       * @param key the key to search
29       * @return true if the key was found; false otherwise
30       */
31      boolean contains(Object key);
32  
33      /**
34       * Returns the value of the key. If the key can't be found it will throw a exception.
35       *
36       * @param key the key of the value to look up.
37       * @return returns the value associated with the key
38       * @throws ContextException if the key doesn't exist
39       */
40      Object get(Object key) throws ContextException;
41  
42      /**
43       * Utility method to retrieve containerContext data.
44       * The returned Map is an unmodifiable view.
45       * @return the containerContext data
46       * @since 1.0-alpha-18
47       */
48      Map<Object, Object> getContextData();
49  
50      /**
51       * Adds the item to the containerContext.
52       *
53       * @param key the key of the item
54       * @param value the item
55       * @throws IllegalStateException if this context is read-only
56       */
57      public void put(Object key, Object value) throws IllegalStateException;
58  
59      // todo [dain] this isn't needed anymore since containers are no longer nestable
60      /**
61       * Hides the item in the containerContext.
62       * After remove(key) has been called, a get(key)
63       * will always fail, even if the parent containerContext
64       * has such a mapping.
65       *
66       * @param key the items key
67       * @throws IllegalStateException if this context is read-only
68       */
69      void hide(Object key) throws IllegalStateException;
70  
71      /**
72       * Make the containerContext read-only.
73       * Any attempt to write to the containerContext via put()
74       * will result in an IllegalStateException.
75       */
76      void makeReadOnly();
77  }