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