KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > crypto > dsig > Reference


1 /*
2  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
3  */
4 /*
5  * $Id: Reference.java,v 1.9 2005/05/10 16:03:46 mullan Exp $
6  */
7 package javax.xml.crypto.dsig;
8
9 import javax.xml.crypto.Data;
10 import javax.xml.crypto.URIReference;
11 import javax.xml.crypto.XMLStructure;
12 import java.io.InputStream JavaDoc;
13 import java.util.List JavaDoc;
14
15 /**
16  * A representation of the <code>Reference</code> element as defined in the
17  * <a HREF="http://www.w3.org/TR/xmldsig-core/">
18  * W3C Recommendation for XML-Signature Syntax and Processing</a>.
19  * The XML schema is defined as:
20  * <code><pre>
21  * &lt;element name="Reference" type="ds:ReferenceType"/&gt;
22  * &lt;complexType name="ReferenceType"&gt;
23  * &lt;sequence&gt;
24  * &lt;element ref="ds:Transforms" minOccurs="0"/&gt;
25  * &lt;element ref="ds:DigestMethod"/&gt;
26  * &lt;element ref="ds:DigestValue"/&gt;
27  * &lt;/sequence&gt;
28  * &lt;attribute name="Id" type="ID" use="optional"/&gt;
29  * &lt;attribute name="URI" type="anyURI" use="optional"/&gt;
30  * &lt;attribute name="Type" type="anyURI" use="optional"/&gt;
31  * &lt;/complexType&gt;
32  *
33  * &lt;element name="DigestValue" type="ds:DigestValueType"/&gt;
34  * &lt;simpleType name="DigestValueType"&gt;
35  * &lt;restriction base="base64Binary"/&gt;
36  * &lt;/simpleType&gt;
37  * </pre></code>
38  *
39  * <p>A <code>Reference</code> instance may be created by invoking one of the
40  * {@link XMLSignatureFactory#newReference newReference} methods of the
41  * {@link XMLSignatureFactory} class; for example:
42  *
43  * <pre>
44  * XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
45  * Reference ref = factory.newReference
46  * ("http://www.ietf.org/rfc/rfc3275.txt",
47  * factory.newDigestMethod(DigestMethod.SHA1, null));
48  * </pre>
49  *
50  * @author Sean Mullan
51  * @author Erwin van der Koogh
52  * @author JSR 105 Expert Group
53  * @since 1.6
54  * @see XMLSignatureFactory#newReference(String, DigestMethod)
55  * @see XMLSignatureFactory#newReference(String, DigestMethod, List, String, String)
56  */
57 public interface Reference extends URIReference, XMLStructure {
58
59     /**
60      * Returns an {@link java.util.Collections#unmodifiableList unmodifiable
61      * list} of {@link Transform}s that are contained in this
62      * <code>Reference</code>.
63      *
64      * @return an unmodifiable list of <code>Transform</code>s
65      * (may be empty but never <code>null</code>)
66      */
67     List JavaDoc getTransforms();
68
69     /**
70      * Returns the digest method of this <code>Reference</code>.
71      *
72      * @return the digest method
73      */
74     DigestMethod getDigestMethod();
75
76     /**
77      * Returns the optional <code>Id</code> attribute of this
78      * <code>Reference</code>, which permits this reference to be
79      * referenced from elsewhere.
80      *
81      * @return the <code>Id</code> attribute (may be <code>null</code> if not
82      * specified)
83      */
84     String JavaDoc getId();
85
86     /**
87      * Returns the digest value of this <code>Reference</code>.
88      *
89      * @return the raw digest value, or <code>null</code> if this reference has
90      * not been digested yet. Each invocation of this method returns a new
91      * clone to protect against subsequent modification.
92      */
93     byte[] getDigestValue();
94
95     /**
96      * Returns the calculated digest value of this <code>Reference</code>
97      * after a validation operation. This method is useful for debugging if
98      * the reference fails to validate.
99      *
100      * @return the calculated digest value, or <code>null</code> if this
101      * reference has not been validated yet. Each invocation of this method
102      * returns a new clone to protect against subsequent modification.
103      */
104     byte[] getCalculatedDigestValue();
105
106     /**
107      * Validates this reference. This method verifies the digest of this
108      * reference.
109      *
110      * <p>This method only validates the reference the first time it is
111      * invoked. On subsequent invocations, it returns a cached result.
112      *
113      * @return <code>true</code> if this reference was validated successfully;
114      * <code>false</code> otherwise
115      * @param validateContext the validating context
116      * @throws NullPointerException if <code>validateContext</code> is
117      * <code>null</code>
118      * @throws XMLSignatureException if an unexpected exception occurs while
119      * validating the reference
120      */
121     boolean validate(XMLValidateContext validateContext)
122     throws XMLSignatureException;
123
124     /**
125      * Returns the dereferenced data, if
126      * <a HREF="XMLSignContext.html#Supported Properties">reference caching</a>
127      * is enabled. This is the result of dereferencing the URI of this
128      * reference during a validation or generation operation.
129      *
130      * @return the dereferenced data, or <code>null</code> if reference
131      * caching is not enabled or this reference has not been generated or
132      * validated
133      */
134     Data getDereferencedData();
135
136     /**
137      * Returns the pre-digested input stream, if
138      * <a HREF="XMLSignContext.html#Supported Properties">reference caching</a>
139      * is enabled. This is the input to the digest operation during a
140      * validation or signing operation.
141      *
142      * @return an input stream containing the pre-digested input, or
143      * <code>null</code> if reference caching is not enabled or this
144      * reference has not been generated or validated
145      */
146     InputStream JavaDoc getDigestInputStream();
147 }
148
Popular Tags