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 
  27 /**
  28  * {@code ReferenceList} is an element that contains pointers from a key
  29  * value of an {@code EncryptedKey} to items encrypted by that key value
  30  * ({@code EncryptedData} or {@code EncryptedKey} elements).
  31  * <p>
  32  * It is defined as follows:
  33  * <pre>{@code
  34  * <element name='ReferenceList'>
  35  *     <complexType>
  36  *         <choice minOccurs='1' maxOccurs='unbounded'>
  37  *             <element name='DataReference' type='xenc:ReferenceType'/>
  38  *             <element name='KeyReference' type='xenc:ReferenceType'/>
  39  *         </choice>
  40  *     </complexType>
  41  * </element>
  42  * }</pre>
  43  *
  44  * @author Axl Mattheus
  45  * @see Reference
  46  */
  47 public interface ReferenceList {
  48 
  49     /** DATA TAG */
  50     int DATA_REFERENCE = 0x00000001;
  51 
  52     /** KEY TAG */
  53     int KEY_REFERENCE  = 0x00000002;
  54 
  55     /**
  56      * Adds a reference to this reference list.
  57      *
  58      * @param reference the reference to add.
  59      * @throws IllegalAccessException if the {@code Reference} is not an
  60      *   instance of {@code DataReference} or {@code KeyReference}.
  61      */
  62     void add(Reference reference);
  63 
  64     /**
  65      * Removes a reference from the {@code ReferenceList}.
  66      *
  67      * @param reference the reference to remove.
  68      */
  69     void remove(Reference reference);
  70 
  71     /**
  72      * Returns the size of the {@code ReferenceList}.
  73      *
  74      * @return the size of the {@code ReferenceList}.
  75      */
  76     int size();
  77 
  78     /**
  79      * Indicates if the {@code ReferenceList} is empty.
  80      *
  81      * @return <b>{@code true}</b> if the {@code ReferenceList} is
  82      *     empty, else <b>{@code false}</b>.
  83      */
  84     boolean isEmpty();
  85 
  86     /**
  87      * Returns an {@code Iterator} over all the {@code Reference}s
  88      * contained in this {@code ReferenceList}.
  89      *
  90      * @return Iterator.
  91      */
  92     Iterator<Reference> getReferences();
  93 
  94     /**
  95      * {@code DataReference} factory method. Returns a
  96      * {@code DataReference}.
  97      * @param uri
  98      * @return a {@code DataReference}.
  99      */
 100     Reference newDataReference(String uri);
 101 
 102     /**
 103      * {@code KeyReference} factory method. Returns a
 104      * {@code KeyReference}.
 105      * @param uri
 106      * @return a {@code KeyReference}.
 107      */
 108     Reference newKeyReference(String uri);
 109 }