1/* 2 * Copyright (c) 2005, 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: XMLCryptoContext.java,v 1.6 2005/05/10 15:47:42 mullan Exp $ 27 */ 28package javax.xml.crypto; 29 30/** 31 * Contains common context information for XML cryptographic operations. 32 * 33 * <p>This interface contains methods for setting and retrieving properties 34 * that affect the processing of XML signatures or XML encrypted structures. 35 * 36 * <p>Note that <code>XMLCryptoContext</code> instances can contain information 37 * and state specific to the XML cryptographic structure it is used with. 38 * The results are unpredictable if an <code>XMLCryptoContext</code> is 39 * used with multiple structures (for example, you should not use the same 40 * {@link javax.xml.crypto.dsig.XMLValidateContext} instance to validate two 41 * different {@link javax.xml.crypto.dsig.XMLSignature} objects). 42 * 43 * @author Sean Mullan 44 * @author JSR 105 Expert Group 45 * @since 1.6 46 */ 47public interface XMLCryptoContext { 48 49 /** 50 * Returns the base URI. 51 * 52 * @return the base URI, or <code>null</code> if not specified 53 * @see #setBaseURI(String) 54 */ 55 String getBaseURI(); 56 57 /** 58 * Sets the base URI. 59 * 60 * @param baseURI the base URI, or <code>null</code> to remove current 61 * value 62 * @throws IllegalArgumentException if <code>baseURI</code> is not RFC 63 * 2396 compliant 64 * @see #getBaseURI 65 */ 66 void setBaseURI(String baseURI); 67 68 /** 69 * Returns the key selector for finding a key. 70 * 71 * @return the key selector, or <code>null</code> if not specified 72 * @see #setKeySelector(KeySelector) 73 */ 74 KeySelector getKeySelector(); 75 76 /** 77 * Sets the key selector for finding a key. 78 * 79 * @param ks the key selector, or <code>null</code> to remove the current 80 * setting 81 * @see #getKeySelector 82 */ 83 void setKeySelector(KeySelector ks); 84 85 /** 86 * Returns a <code>URIDereferencer</code> that is used to dereference 87 * {@link URIReference}s. 88 * 89 * @return the <code>URIDereferencer</code>, or <code>null</code> if not 90 * specified 91 * @see #setURIDereferencer(URIDereferencer) 92 */ 93 URIDereferencer getURIDereferencer(); 94 95 /** 96 * Sets a <code>URIDereferencer</code> that is used to dereference 97 * {@link URIReference}s. The specified <code>URIDereferencer</code> 98 * is used in place of an implementation's default 99 * <code>URIDereferencer</code>. 100 * 101 * @param dereferencer the <code>URIDereferencer</code>, or 102 * <code>null</code> to remove any current setting 103 * @see #getURIDereferencer 104 */ 105 void setURIDereferencer(URIDereferencer dereferencer); 106 107 /** 108 * Returns the namespace prefix that the specified namespace URI is 109 * associated with. Returns the specified default prefix if the specified 110 * namespace URI has not been bound to a prefix. To bind a namespace URI 111 * to a prefix, call the {@link #putNamespacePrefix putNamespacePrefix} 112 * method. 113 * 114 * @param namespaceURI a namespace URI 115 * @param defaultPrefix the prefix to be returned in the event that the 116 * the specified namespace URI has not been bound to a prefix. 117 * @return the prefix that is associated with the specified namespace URI, 118 * or <code>defaultPrefix</code> if the URI is not registered. If 119 * the namespace URI is registered but has no prefix, an empty string 120 * (<code>""</code>) is returned. 121 * @throws NullPointerException if <code>namespaceURI</code> is 122 * <code>null</code> 123 * @see #putNamespacePrefix(String, String) 124 */ 125 String getNamespacePrefix(String namespaceURI, String defaultPrefix); 126 127 /** 128 * Maps the specified namespace URI to the specified prefix. If there is 129 * already a prefix associated with the specified namespace URI, the old 130 * prefix is replaced by the specified prefix. 131 * 132 * @param namespaceURI a namespace URI 133 * @param prefix a namespace prefix (or <code>null</code> to remove any 134 * existing mapping). Specifying the empty string (<code>""</code>) 135 * binds no prefix to the namespace URI. 136 * @return the previous prefix associated with the specified namespace 137 * URI, or <code>null</code> if there was none 138 * @throws NullPointerException if <code>namespaceURI</code> is 139 * <code>null</code> 140 * @see #getNamespacePrefix(String, String) 141 */ 142 String putNamespacePrefix(String namespaceURI, String prefix); 143 144 /** 145 * Returns the default namespace prefix. The default namespace prefix 146 * is the prefix for all namespace URIs not explicitly set by the 147 * {@link #putNamespacePrefix putNamespacePrefix} method. 148 * 149 * @return the default namespace prefix, or <code>null</code> if none has 150 * been set. 151 * @see #setDefaultNamespacePrefix(String) 152 */ 153 String getDefaultNamespacePrefix(); 154 155 /** 156 * Sets the default namespace prefix. This sets the namespace prefix for 157 * all namespace URIs not explicitly set by the {@link #putNamespacePrefix 158 * putNamespacePrefix} method. 159 * 160 * @param defaultPrefix the default namespace prefix, or <code>null</code> 161 * to remove the current setting. Specify the empty string 162 * (<code>""</code>) to bind no prefix. 163 * @see #getDefaultNamespacePrefix 164 */ 165 void setDefaultNamespacePrefix(String defaultPrefix); 166 167 /** 168 * Sets the specified property. 169 * 170 * @param name the name of the property 171 * @param value the value of the property to be set 172 * @return the previous value of the specified property, or 173 * <code>null</code> if it did not have a value 174 * @throws NullPointerException if <code>name</code> is <code>null</code> 175 * @see #getProperty(String) 176 */ 177 Object setProperty(String name, Object value); 178 179 /** 180 * Returns the value of the specified property. 181 * 182 * @param name the name of the property 183 * @return the current value of the specified property, or 184 * <code>null</code> if it does not have a value 185 * @throws NullPointerException if <code>name</code> is <code>null</code> 186 * @see #setProperty(String, Object) 187 */ 188 Object getProperty(String name); 189 190 /** 191 * Returns the value to which this context maps the specified key. 192 * 193 * <p>More formally, if this context contains a mapping from a key 194 * <code>k</code> to a value <code>v</code> such that 195 * <code>(key==null ? k==null : key.equals(k))</code>, then this method 196 * returns <code>v</code>; otherwise it returns <code>null</code>. (There 197 * can be at most one such mapping.) 198 * 199 * <p>This method is useful for retrieving arbitrary information that is 200 * specific to the cryptographic operation that this context is used for. 201 * 202 * @param key the key whose associated value is to be returned 203 * @return the value to which this context maps the specified key, or 204 * <code>null</code> if there is no mapping for the key 205 * @see #put(Object, Object) 206 */ 207 Object get(Object key); 208 209 /** 210 * Associates the specified value with the specified key in this context. 211 * If the context previously contained a mapping for this key, the old 212 * value is replaced by the specified value. 213 * 214 * <p>This method is useful for storing arbitrary information that is 215 * specific to the cryptographic operation that this context is used for. 216 * 217 * @param key key with which the specified value is to be associated with 218 * @param value value to be associated with the specified key 219 * @return the previous value associated with the key, or <code>null</code> 220 * if there was no mapping for the key 221 * @throws IllegalArgumentException if some aspect of this key or value 222 * prevents it from being stored in this context 223 * @see #get(Object) 224 */ 225 Object put(Object key, Object value); 226} 227