001 /*
002 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 /*
026 * $Id: XMLCryptoContext.java,v 1.6 2005/05/10 15:47:42 mullan Exp $
027 */
028 package javax.xml.crypto;
029
030 /**
031 * Contains common context information for XML cryptographic operations.
032 *
033 * <p>This interface contains methods for setting and retrieving properties
034 * that affect the processing of XML signatures or XML encrypted structures.
035 *
036 * <p>Note that <code>XMLCryptoContext</code> instances can contain information
037 * and state specific to the XML cryptographic structure it is used with.
038 * The results are unpredictable if an <code>XMLCryptoContext</code> is
039 * used with multiple structures (for example, you should not use the same
040 * {@link javax.xml.crypto.dsig.XMLValidateContext} instance to validate two
041 * different {@link javax.xml.crypto.dsig.XMLSignature} objects).
042 *
043 * @author Sean Mullan
044 * @author JSR 105 Expert Group
045 * @since 1.6
046 */
047 public interface XMLCryptoContext {
048
049 /**
050 * Returns the base URI.
051 *
052 * @return the base URI, or <code>null</code> if not specified
053 * @see #setBaseURI(String)
054 */
055 String getBaseURI();
056
057 /**
058 * Sets the base URI.
059 *
060 * @param baseURI the base URI, or <code>null</code> to remove current
061 * value
062 * @throws IllegalArgumentException if <code>baseURI</code> is not RFC
063 * 2396 compliant
064 * @see #getBaseURI
065 */
066 void setBaseURI(String baseURI);
067
068 /**
069 * Returns the key selector for finding a key.
070 *
071 * @return the key selector, or <code>null</code> if not specified
072 * @see #setKeySelector(KeySelector)
073 */
074 KeySelector getKeySelector();
075
076 /**
077 * Sets the key selector for finding a key.
078 *
079 * @param ks the key selector, or <code>null</code> to remove the current
080 * setting
081 * @see #getKeySelector
082 */
083 void setKeySelector(KeySelector ks);
084
085 /**
086 * Returns a <code>URIDereferencer</code> that is used to dereference
087 * {@link URIReference}s.
088 *
089 * @return the <code>URIDereferencer</code>, or <code>null</code> if not
090 * specified
091 * @see #setURIDereferencer(URIDereferencer)
092 */
093 URIDereferencer getURIDereferencer();
094
095 /**
096 * Sets a <code>URIDereferencer</code> that is used to dereference
097 * {@link URIReference}s. The specified <code>URIDereferencer</code>
098 * is used in place of an implementation's default
099 * <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 }
|