javax.xml.crypto.dsig.Transform Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of xmlsec Show documentation
Apache XML Security for Java supports XML-Signature Syntax and Processing, W3C Recommendation 12 February 2002, and XML Encryption Syntax and Processing, W3C Recommendation 10 December 2002. As of version 1.4, the library supports the standard Java API JSR-105: XML Digital Signature APIs.
There is a newer version: 4.0.2
Show newest version
/**
 * 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: Transform.java 1333869 2012-05-04 10:42:44Z coheigea $
 */
package javax.xml.crypto.dsig;

import java.io.OutputStream;
import java.security.spec.AlgorithmParameterSpec;
import javax.xml.crypto.AlgorithmMethod;
import javax.xml.crypto.Data;
import javax.xml.crypto.XMLCryptoContext;
import javax.xml.crypto.XMLStructure;
import javax.xml.crypto.dsig.spec.TransformParameterSpec;

/**
 * A representation of the XML Transform element as 
 * defined in the 
 * W3C Recommendation for XML-Signature Syntax and Processing. 
 * The XML Schema Definition is defined as:
 *
 *  * <element name="Transform" type="ds:TransformType"/>
 *   <complexType name="TransformType" mixed="true">
 *     <choice minOccurs="0" maxOccurs="unbounded">
 *       <any namespace="##other" processContents="lax"/>
 *       <!-- (1,1) elements from (0,unbounded) namespaces -->
 *       <element name="XPath" type="string"/>
 *     </choice>
 *     <attribute name="Algorithm" type="anyURI" use="required"/>
 *   </complexType>
 * 
 *
 * A Transform instance may be created by invoking the
 * {@link XMLSignatureFactory#newTransform newTransform} method 
 * of the {@link XMLSignatureFactory} class.
 *
 * @author Sean Mullan
 * @author JSR 105 Expert Group
 * @see XMLSignatureFactory#newTransform(String, TransformParameterSpec)
 */
public interface Transform extends XMLStructure, AlgorithmMethod {

    /**
     * The Base64 
     * transform algorithm URI.
     */
    String BASE64 = "http://www.w3.org/2000/09/xmldsig#base64";

    /**
     * The 
     * Enveloped Signature transform algorithm URI.
     */
    String ENVELOPED = 
        "http://www.w3.org/2000/09/xmldsig#enveloped-signature";

    /**
     * The XPath 
     * transform algorithm URI.
     */
    String XPATH = "http://www.w3.org/TR/1999/REC-xpath-19991116";

    /**
     * The 
     * XPath Filter 2 transform algorithm URI.
     */
    String XPATH2 = "http://www.w3.org/2002/06/xmldsig-filter2";

    /**
     * The XSLT 
     * transform algorithm URI.
     */
    String XSLT = "http://www.w3.org/TR/1999/REC-xslt-19991116";

    /**
     * Returns the algorithm-specific input parameters associated with this
     * Transform.
     * 
     * The returned parameters can be typecast to a 
     * {@link TransformParameterSpec} object.
     *
     * @return the algorithm-specific input parameters (may be null
     *    if not specified)
     */
    AlgorithmParameterSpec getParameterSpec();

    /**
     * Transforms the specified data using the underlying transform algorithm.
     *
     * @param data the data to be transformed
     * @param context the XMLCryptoContext containing
     *    additional context (may be null if not applicable)
     * @return the transformed data
     * @throws NullPointerException if data is null
     * @throws TransformException if an error occurs while executing the
     *    transform
     */
    public abstract Data transform(Data data, XMLCryptoContext context)
        throws TransformException;

    /**
     * Transforms the specified data using the underlying transform algorithm.
     * If the output of this transform is an OctetStreamData, then 
     * this method returns null and the bytes are written to the 
     * specified OutputStream. Otherwise, the 
     * OutputStream is ignored and the method behaves as if 
     * {@link #transform(Data, XMLCryptoContext)} were invoked.
     *
     * @param data the data to be transformed
     * @param context the XMLCryptoContext containing
     *    additional context (may be null if not applicable)
     * @param os the OutputStream that should be used to write
     *    the transformed data to
     * @return the transformed data (or null if the data was
     *    written to the OutputStream parameter)
     * @throws NullPointerException if data or os
     *    is null
     * @throws TransformException if an error occurs while executing the
     *    transform
     */
    public abstract Data transform
        (Data data, XMLCryptoContext context, OutputStream os)
        throws TransformException;
}