KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > crypto > dsig > keyinfo > RetrievalMethod


1 /*
2  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
3  */
4 /*
5  * $Id: RetrievalMethod.java,v 1.8 2005/05/10 16:35:35 mullan Exp $
6  */
7 package javax.xml.crypto.dsig.keyinfo;
8
9 import javax.xml.crypto.Data;
10 import javax.xml.crypto.URIReference;
11 import javax.xml.crypto.URIReferenceException;
12 import javax.xml.crypto.XMLCryptoContext;
13 import javax.xml.crypto.XMLStructure;
14 import javax.xml.crypto.dsig.Transform;
15 import java.util.List JavaDoc;
16
17 /**
18  * A representation of the XML <code>RetrievalMethod</code> element as
19  * defined in the <a HREF="http://www.w3.org/TR/xmldsig-core/">
20  * W3C Recommendation for XML-Signature Syntax and Processing</a>.
21  * A <code>RetrievalMethod</code> object is used to convey a reference to
22  * <code>KeyInfo</code> information that is stored at another location.
23  * The XML schema definition is defined as:
24  *
25  * <pre>
26  * &lt;element name="RetrievalMethod" type="ds:RetrievalMethodType"/&gt;
27  * &lt;complexType name="RetrievalMethodType"&gt;
28  * &lt;sequence&gt;
29  * &lt;element name="Transforms" type="ds:TransformsType" minOccurs="0"/&gt;
30  * &lt;/sequence&gt;
31  * &lt;attribute name="URI" type="anyURI"/&gt;
32  * &lt;attribute name="Type" type="anyURI" use="optional"/&gt;
33  * &lt;/complexType&gt;
34  * </pre>
35  *
36  * A <code>RetrievalMethod</code> instance may be created by invoking one of the
37  * {@link KeyInfoFactory#newRetrievalMethod newRetrievalMethod} methods
38  * of the {@link KeyInfoFactory} class, and passing it the URI
39  * identifying the location of the KeyInfo, an optional type URI identifying
40  * the type of KeyInfo, and an optional list of {@link Transform}s; for example:
41  * <pre>
42  * KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
43  * RetrievalMethod rm = factory.newRetrievalMethod
44  * ("#KeyValue-1", KeyValue.DSA_TYPE, Collections.singletonList(Transform.BASE64));
45  * </pre>
46  *
47  * @author Sean Mullan
48  * @author JSR 105 Expert Group
49  * @since 1.6
50  * @see KeyInfoFactory#newRetrievalMethod(String)
51  * @see KeyInfoFactory#newRetrievalMethod(String, String, List)
52  */
53 public interface RetrievalMethod extends URIReference, XMLStructure {
54
55     /**
56      * Returns an {@link java.util.Collections#unmodifiableList unmodifiable
57      * list} of {@link Transform}s of this <code>RetrievalMethod</code>.
58      *
59      * @return an unmodifiable list of <code>Transform</code> objects (may be
60      * empty but never <code>null</code>).
61      */
62     List JavaDoc getTransforms();
63
64     /**
65      * Returns the URI of the referenced <code>KeyInfo</code> information.
66      *
67      * @return the URI of the referenced <code>KeyInfo</code> information in
68      * RFC 2396 format (never <code>null</code>)
69      */
70     String JavaDoc getURI();
71
72    /**
73     * Dereferences the <code>KeyInfo</code> information referenced by this
74     * <code>RetrievalMethod</code> and applies the specified
75     * <code>Transform</code>s.
76     *
77     * @param context an <code>XMLCryptoContext</code> that may contain
78     * additional useful information for dereferencing the URI. The
79     * context's <code>baseURI</code> and <code>dereferencer</code>
80     * parameters (if specified) are used to resolve and dereference this
81     * <code>RetrievalMethod</code>
82     * @return a <code>Data</code> object representing the raw contents of the
83     * <code>KeyInfo</code> information referenced by this
84     * <code>RetrievalMethod</code>. It is the caller's responsibility to
85     * convert the returned data to an appropriate
86     * <code>KeyInfo</code> object.
87     * @throws NullPointerException if <code>context</code> is <code>null</code>
88     * @throws URIReferenceException if there is an error while dereferencing
89     */
90     Data dereference(XMLCryptoContext context) throws URIReferenceException;
91 }
92
Popular Tags