Back to index...

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

Back to index...