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 */
23package com.sun.org.apache.xml.internal.security.encryption;
24
25import java.util.Iterator;
26import 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 */
46public 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}
100