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      /**
27       * Returns true if this context contains a value for the specified key.
28       *
29       * @param key the key to search
30       * @return true if the key was found; false otherwise
31       */
32      boolean contains( Object key );
33  
34      /**
35       * Returns the value of the key. If the key can't be found it will throw a exception.
36       *
37       * @param key the key of the value to look up.
38       * @return returns the value associated with the key
39       * @throws ContextException if the key doesn't exist
40       */
41      Object get( Object key )
42          throws ContextException;
43  
44      /**
45       * Utility method to retrieve containerContext data.
46       * The returned Map is an unmodifiable view.
47       * @return the containerContext data
48       * @since 1.0-alpha-18
49       */
50      Map<Object, Object> getContextData();
51  
52      /**
53       * Adds the item to the containerContext.
54       *
55       * @param key the key of the item
56       * @param value the item
57       * @throws IllegalStateException if this context is read-only
58       */
59      public void put( Object key, Object value )
60          throws IllegalStateException;
61  
62      // todo [dain] this isn't needed anymore since containers are no longer nestable
63      /**
64       * Hides the item in the containerContext.
65       * After remove(key) has been called, a get(key)
66       * will always fail, even if the parent containerContext
67       * has such a mapping.
68       *
69       * @param key the items key
70       * @throws IllegalStateException if this context is read-only
71       */
72      void hide( Object key )
73          throws IllegalStateException;
74  
75      /**
76       * Make the containerContext read-only.
77       * Any attempt to write to the containerContext via put()
78       * will result in an IllegalStateException.
79       */
80      void makeReadOnly();
81  }