1/* 2 * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25/* 26 * $Id: RetrievalMethod.java,v 1.8 2005/05/10 16:35:35 mullan Exp $ 27 */ 28package javax.xml.crypto.dsig.keyinfo; 29 30import javax.xml.crypto.Data; 31import javax.xml.crypto.URIReference; 32import javax.xml.crypto.URIReferenceException; 33import javax.xml.crypto.XMLCryptoContext; 34import javax.xml.crypto.XMLStructure; 35import javax.xml.crypto.dsig.Transform; 36import java.util.List; 37 38/** 39 * A representation of the XML <code>RetrievalMethod</code> element as 40 * defined in the <a href="http://www.w3.org/TR/xmldsig-core/"> 41 * W3C Recommendation for XML-Signature Syntax and Processing</a>. 42 * A <code>RetrievalMethod</code> object is used to convey a reference to 43 * <code>KeyInfo</code> information that is stored at another location. 44 * The XML schema definition is defined as: 45 * 46 * <pre> 47 * <element name="RetrievalMethod" type="ds:RetrievalMethodType"/> 48 * <complexType name="RetrievalMethodType"> 49 * <sequence> 50 * <element name="Transforms" type="ds:TransformsType" minOccurs="0"/> 51 * </sequence> 52 * <attribute name="URI" type="anyURI"/> 53 * <attribute name="Type" type="anyURI" use="optional"/> 54 * </complexType> 55 * </pre> 56 * 57 * A <code>RetrievalMethod</code> instance may be created by invoking one of the 58 * {@link KeyInfoFactory#newRetrievalMethod newRetrievalMethod} methods 59 * of the {@link KeyInfoFactory} class, and passing it the URI 60 * identifying the location of the KeyInfo, an optional type URI identifying 61 * the type of KeyInfo, and an optional list of {@link Transform}s; for example: 62 * <pre> 63 * KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM"); 64 * RetrievalMethod rm = factory.newRetrievalMethod 65 * ("#KeyValue-1", KeyValue.DSA_TYPE, Collections.singletonList(Transform.BASE64)); 66 * </pre> 67 * 68 * @author Sean Mullan 69 * @author JSR 105 Expert Group 70 * @since 1.6 71 * @see KeyInfoFactory#newRetrievalMethod(String) 72 * @see KeyInfoFactory#newRetrievalMethod(String, String, List) 73 */ 74public interface RetrievalMethod extends URIReference, XMLStructure { 75 76 /** 77 * Returns an {@link java.util.Collections#unmodifiableList unmodifiable 78 * list} of {@link Transform}s of this <code>RetrievalMethod</code>. 79 * 80 * @return an unmodifiable list of <code>Transform</code> objects (may be 81 * empty but never <code>null</code>). 82 */ 83 List<Transform> getTransforms(); 84 85 /** 86 * Returns the URI of the referenced <code>KeyInfo</code> information. 87 * 88 * @return the URI of the referenced <code>KeyInfo</code> information in 89 * RFC 2396 format (never <code>null</code>) 90 */ 91 String getURI(); 92 93 /** 94 * Dereferences the <code>KeyInfo</code> information referenced by this 95 * <code>RetrievalMethod</code> and applies the specified 96 * <code>Transform</code>s. 97 * 98 * @param context an <code>XMLCryptoContext</code> that may contain 99 * additional useful information for dereferencing the URI. The 100 * context's <code>baseURI</code> and <code>dereferencer</code> 101 * parameters (if specified) are used to resolve and dereference this 102 * <code>RetrievalMethod</code> 103 * @return a <code>Data</code> object representing the raw contents of the 104 * <code>KeyInfo</code> information referenced by this 105 * <code>RetrievalMethod</code>. It is the caller's responsibility to 106 * convert the returned data to an appropriate 107 * <code>KeyInfo</code> object. 108 * @throws NullPointerException if <code>context</code> is <code>null</code> 109 * @throws URIReferenceException if there is an error while dereferencing 110 */ 111 Data dereference(XMLCryptoContext context) throws URIReferenceException; 112} 113