XMLCryptoContext


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