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