/*
* 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);
}