View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * Copyright 2000-2002,2004 The Apache Software 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  package com.sun.org.apache.xerces.internal.xni;
22  
23  import java.util.Enumeration;
24  
25  /**
26   * The Augmentations interface defines a table of additional data that may
27   * be passed along the document pipeline. The information can contain extra
28   * arguments or infoset augmentations, for example PSVI. This additional
29   * information is identified by a String key.
30   * <p>
31   * <strong>Note:</strong>
32   * Methods that receive Augmentations are required to copy the information
33   * if it is to be saved for use beyond the scope of the method.
34   * The Augmentations content is volatile, and maybe modified by any method in
35   * any component in the pipeline. Therefore, methods passed this structure
36   * should not save any reference to the structure.
37   *
38   * @author Elena Litani, IBM
39   */
40  
41  public interface Augmentations {
42  
43  
44      /**
45       * Add additional information identified by a key to the Augmentations structure.
46       *
47       * @param key    Identifier, can't be <code>null</code>
48       * @param item   Additional information
49       *
50       * @return the previous value of the specified key in the Augmentations structure,
51       *         or <code>null</code> if it did not have one.
52       */
53      public Object putItem (String key, Object item);
54  
55  
56      /**
57       * Get information identified by a key from the Augmentations structure
58       *
59       * @param key    Identifier, can't be <code>null</code>
60       *
61       * @return the value to which the key is mapped in the Augmentations structure;
62       *         <code>null</code> if the key is not mapped to any value.
63       */
64      public Object getItem(String key);
65  
66  
67      /**
68       * Remove additional info from the Augmentations structure
69       *
70       * @param key    Identifier, can't be <code>null</code>
71       * @return the previous value of the specified key in the Augmentations structure,
72       *         or <code>null</code> if it did not have one.
73       */
74      public Object removeItem (String key);
75  
76  
77      /**
78       * Returns an enumeration of the keys in the Augmentations structure
79       *
80       */
81      public Enumeration keys ();
82  
83  
84      /**
85       * Remove all objects from the Augmentations structure.
86       */
87      public void removeAllItems ();
88  
89  }