Java tutorial
/* * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /* * $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); }