1 /*
   2  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
   3  */
   4 /*
   5  * Licensed to the Apache Software Foundation (ASF) under one or more
   6  * contributor license agreements.  See the NOTICE file distributed with
   7  * this work for additional information regarding copyright ownership.
   8  * The ASF licenses this file to You under the Apache License, Version 2.0
   9  * (the "License"); you may not use this file except in compliance with
  10  * the License.  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  * @LastModified: Oct 2017
  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 }