1 /*
   2  * reserved comment block
   3  * DO NOT REMOVE OR ALTER!
   4  */
   5 /**
   6  * Licensed to the Apache Software Foundation (ASF) under one
   7  * or more contributor license agreements. See the NOTICE file
   8  * distributed with this work for additional information
   9  * regarding copyright ownership. The ASF licenses this file
  10  * to you under the Apache License, Version 2.0 (the
  11  * "License"); you may not use this file except in compliance
  12  * with the License. You may obtain a copy of the License at
  13  *
  14  * http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  * Unless required by applicable law or agreed to in writing,
  17  * software distributed under the License is distributed on an
  18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  19  * KIND, either express or implied. See the License for the
  20  * specific language governing permissions and limitations
  21  * under the License.
  22  */
  23 package com.sun.org.apache.xml.internal.security.encryption;
  24 
  25 import java.util.Iterator;
  26 import org.w3c.dom.Element;
  27 
  28 /**
  29  * A wrapper for a pointer from a key value of an {@code EncryptedKey} to
  30  * items encrypted by that key value ({@code EncryptedData} or
  31  * {@code EncryptedKey} elements).
  32  * <p>
  33  * It is defined as follows:
  34  * <pre>{@code
  35  * <complexType name='ReferenceType'>
  36  *     <sequence>
  37  *         <any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
  38  *     </sequence>
  39  *     <attribute name='URI' type='anyURI' use='required'/>
  40  * </complexType>
  41  * }</pre>
  42  *
  43  * @author Axl Mattheus
  44  * @see ReferenceList
  45  */
  46 public interface Reference {
  47     /**
  48      * Returns the {@code Element} tag name for this {@code Reference}.
  49      *
  50      * @return the tag name of this {@code Reference}.
  51      */
  52     String getType();
  53 
  54     /**
  55      * Returns a {@code URI} that points to an {@code Element} that
  56      * were encrypted using the key defined in the enclosing
  57      * {@code EncryptedKey} element.
  58      *
  59      * @return an Uniform Resource Identifier that qualifies an
  60      *   {@code EncryptedType}.
  61      */
  62     String getURI();
  63 
  64     /**
  65      * Sets a {@code URI} that points to an {@code Element} that
  66      * were encrypted using the key defined in the enclosing
  67      * {@code EncryptedKey} element.
  68      *
  69      * @param uri the Uniform Resource Identifier that qualifies an
  70      *   {@code EncryptedType}.
  71      */
  72     void setURI(String uri);
  73 
  74     /**
  75      * Returns an {@code Iterator} over all the child elements contained in
  76      * this {@code Reference} that will aid the recipient in retrieving the
  77      * {@code EncryptedKey} and/or {@code EncryptedData} elements.
  78      * These could include information such as XPath transforms, decompression
  79      * transforms, or information on how to retrieve the elements from a
  80      * document storage facility.
  81      *
  82      * @return child elements.
  83      */
  84     Iterator<Element> getElementRetrievalInformation();
  85 
  86     /**
  87      * Adds retrieval information.
  88      *
  89      * @param info
  90      */
  91     void addElementRetrievalInformation(Element info);
  92 
  93     /**
  94      * Removes the specified retrieval information.
  95      *
  96      * @param info
  97      */
  98     void removeElementRetrievalInformation(Element info);
  99 }