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