01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17:
18: package org.apache.xerces.xni;
19:
20: import java.util.Enumeration;
21:
22: /**
23: * The Augmentations interface defines a table of additional data that may
24: * be passed along the document pipeline. The information can contain extra
25: * arguments or infoset augmentations, for example PSVI. This additional
26: * information is identified by a String key.
27: * <p>
28: * <strong>Note:</strong>
29: * Methods that receive Augmentations are required to copy the information
30: * if it is to be saved for use beyond the scope of the method.
31: * The Augmentations content is volatile, and maybe modified by any method in
32: * any component in the pipeline. Therefore, methods passed this structure
33: * should not save any reference to the structure.
34: *
35: * @author Elena Litani, IBM
36: * @version $Id: Augmentations.java 447247 2006-09-18 05:23:52Z mrglavas $
37: */
38:
39: public interface Augmentations {
40:
41: /**
42: * Add additional information identified by a key to the Augmentations structure.
43: *
44: * @param key Identifier, can't be <code>null</code>
45: * @param item Additional information
46: *
47: * @return the previous value of the specified key in the Augmentations structure,
48: * or <code>null</code> if it did not have one.
49: */
50: public Object putItem(String key, Object item);
51:
52: /**
53: * Get information identified by a key from the Augmentations structure
54: *
55: * @param key Identifier, can't be <code>null</code>
56: *
57: * @return the value to which the key is mapped in the Augmentations structure;
58: * <code>null</code> if the key is not mapped to any value.
59: */
60: public Object getItem(String key);
61:
62: /**
63: * Remove additional info from the Augmentations structure
64: *
65: * @param key Identifier, can't be <code>null</code>
66: * @return the previous value of the specified key in the Augmentations structure,
67: * or <code>null</code> if it did not have one.
68: */
69: public Object removeItem(String key);
70:
71: /**
72: * Returns an enumeration of the keys in the Augmentations structure
73: *
74: */
75: public Enumeration keys();
76:
77: /**
78: * Remove all objects from the Augmentations structure.
79: */
80: public void removeAllItems();
81:
82: }
|