javax.xml.crypto.XMLCryptoContext Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* Copyright 2005 Sun Microsystems, Inc. All rights reserved.
*/
/*
* $Id: XMLCryptoContext.java 1092655 2011-04-15 10:24:18Z coheigea $
*/
package javax.xml.crypto;
/**
* Contains common context information for XML cryptographic operations.
*
* This interface contains methods for setting and retrieving properties
* that affect the processing of XML signatures or XML encrypted structures.
*
*
Note that XMLCryptoContext instances can contain information
* and state specific to the XML cryptographic structure it is used with.
* The results are unpredictable if an XMLCryptoContext 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
*/
public interface XMLCryptoContext {
/**
* Returns the base URI.
*
* @return the base URI, or null if not specified
* @see #setBaseURI(String)
*/
String getBaseURI();
/**
* Sets the base URI.
*
* @param baseURI the base URI, or null to remove current
* value
* @throws IllegalArgumentException if baseURI is not RFC
* 2396 compliant
* @see #getBaseURI
*/
void setBaseURI(String baseURI);
/**
* Returns the key selector for finding a key.
*
* @return the key selector, or null if not specified
* @see #setKeySelector(KeySelector)
*/
KeySelector getKeySelector();
/**
* Sets the key selector for finding a key.
*
* @param ks the key selector, or null to remove the current
* setting
* @see #getKeySelector
*/
void setKeySelector(KeySelector ks);
/**
* Returns a URIDereferencer that is used to dereference
* {@link URIReference}s.
*
* @return the URIDereferencer, or null if not
* specified
* @see #setURIDereferencer(URIDereferencer)
*/
URIDereferencer getURIDereferencer();
/**
* Sets a URIDereferencer that is used to dereference
* {@link URIReference}s. The specified URIDereferencer
* is used in place of an implementation's default
* URIDereferencer.
*
* @param dereferencer the URIDereferencer, or
* null 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 defaultPrefix if the URI is not registered. If
* the namespace URI is registered but has no prefix, an empty string
* ("") is returned.
* @throws NullPointerException if namespaceURI is
* null
* @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 null to remove any
* existing mapping). Specifying the empty string ("")
* binds no prefix to the namespace URI.
* @return the previous prefix associated with the specified namespace
* URI, or null if there was none
* @throws NullPointerException if namespaceURI is
* null
* @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 null 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 null
* to remove the current setting. Specify the empty string
* ("") 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
* null if it did not have a value
* @throws NullPointerException if name is null
* @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
* null if it does not have a value
* @throws NullPointerException if name is null
* @see #setProperty(String, Object)
*/
Object getProperty(String name);
/**
* Returns the value to which this context maps the specified key.
*
*
More formally, if this context contains a mapping from a key
* k to a value v such that
* (key==null ? k==null : key.equals(k)), then this method
* returns v; otherwise it returns null. (There
* can be at most one such mapping.)
*
*
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
* null 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.
*
*
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 null
* 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);
}