Java example source code file (XMLCryptoContext.java)

This example Java source code file (XMLCryptoContext.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

keyselector, object, string, uridereferencer, xmlcryptocontext

The XMLCryptoContext.java Java example source code

/*
 * 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 XMLCryptoContext instances can contain information
 * and state specific to the XML cryptographic structure it is used with.
 * The results are unpredictable if an <code>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
 * @since 1.6
 */
public interface XMLCryptoContext {

    /**
     * Returns the base URI.
     *
     * @return the base URI, or <code>null if not specified
     * @see #setBaseURI(String)
     */
    String getBaseURI();

    /**
     * Sets the base URI.
     *
     * @param baseURI the base URI, or <code>null to remove current
     *    value
     * @throws IllegalArgumentException if <code>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 <code>null if not specified
     * @see #setKeySelector(KeySelector)
     */
    KeySelector getKeySelector();

    /**
     * Sets the key selector for finding a key.
     *
     * @param ks the key selector, or <code>null to remove the current
     *    setting
     * @see #getKeySelector
     */
    void setKeySelector(KeySelector ks);

    /**
     * Returns a <code>URIDereferencer that is used to dereference
     * {@link URIReference}s.
     *
     * @return the <code>URIDereferencer, or null if not
     *    specified
     * @see #setURIDereferencer(URIDereferencer)
     */
    URIDereferencer getURIDereferencer();

    /**
     * Sets a <code>URIDereferencer that is used to dereference
     * {@link URIReference}s. The specified <code>URIDereferencer
     * is used in place of an implementation's default
     * <code>URIDereferencer.
     *
     * @param dereferencer the <code>URIDereferencer, or
     *    <code>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 <code>defaultPrefix if the URI is not registered. If
     *    the namespace URI is registered but has no prefix, an empty string
     *    (<code>"") is returned.
     * @throws NullPointerException if <code>namespaceURI is
     *    <code>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 <code>null to remove any
     *    existing mapping). Specifying the empty string (<code>"")
     *    binds no prefix to the namespace URI.
     * @return the previous prefix associated with the specified namespace
     *    URI, or <code>null if there was none
     * @throws NullPointerException if <code>namespaceURI is
     *    <code>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 <code>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 <code>null
     *    to remove the current setting. Specify the empty string
     *    (<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 if it did not have a value
     * @throws NullPointerException if <code>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
     *    <code>null if it does not have a value
     * @throws NullPointerException if <code>name is null
     * @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 to a value v such that
     * <code>(key==null ? k==null : key.equals(k)), then this method
     * returns <code>v; otherwise it returns null. (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 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
     *    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);
}