javax.xml.crypto.dsig.Reference Maven / Gradle / Ivy
Show all versions of xmlsec Show documentation
/**
* 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: Reference.java 1092655 2011-04-15 10:24:18Z coheigea $
*/
package javax.xml.crypto.dsig;
import javax.xml.crypto.Data;
import javax.xml.crypto.URIReference;
import javax.xml.crypto.XMLStructure;
import java.io.InputStream;
import java.util.List;
/**
* A representation of the Reference element as defined in the
*
* W3C Recommendation for XML-Signature Syntax and Processing.
* The XML schema is defined as:
*
* <element name="Reference" type="ds:ReferenceType"/>
* <complexType name="ReferenceType">
* <sequence>
* <element ref="ds:Transforms" minOccurs="0"/>
* <element ref="ds:DigestMethod"/>
* <element ref="ds:DigestValue"/>
* </sequence>
* <attribute name="Id" type="ID" use="optional"/>
* <attribute name="URI" type="anyURI" use="optional"/>
* <attribute name="Type" type="anyURI" use="optional"/>
* </complexType>
*
* <element name="DigestValue" type="ds:DigestValueType"/>
* <simpleType name="DigestValueType">
* <restriction base="base64Binary"/>
* </simpleType>
*
A Reference instance may be created by invoking one of the
* {@link XMLSignatureFactory#newReference newReference} methods of the
* {@link XMLSignatureFactory} class; for example:
*
*
* XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
* Reference ref = factory.newReference
* ("http://www.ietf.org/rfc/rfc3275.txt",
* factory.newDigestMethod(DigestMethod.SHA1, null));
*
*
* @author Sean Mullan
* @author Erwin van der Koogh
* @author JSR 105 Expert Group
* @see XMLSignatureFactory#newReference(String, DigestMethod)
* @see XMLSignatureFactory#newReference(String, DigestMethod, List, String, String)
*/
public interface Reference extends URIReference, XMLStructure {
/**
* Returns an {@link java.util.Collections#unmodifiableList unmodifiable
* list} of {@link Transform}s that are contained in this
* Reference.
*
* @return an unmodifiable list of Transforms
* (may be empty but never null)
*/
List getTransforms();
/**
* Returns the digest method of this Reference.
*
* @return the digest method
*/
DigestMethod getDigestMethod();
/**
* Returns the optional Id attribute of this
* Reference, which permits this reference to be
* referenced from elsewhere.
*
* @return the Id attribute (may be null if not
* specified)
*/
String getId();
/**
* Returns the digest value of this Reference.
*
* @return the raw digest value, or null if this reference has
* not been digested yet. Each invocation of this method returns a new
* clone to protect against subsequent modification.
*/
byte[] getDigestValue();
/**
* Returns the calculated digest value of this Reference
* after a validation operation. This method is useful for debugging if
* the reference fails to validate.
*
* @return the calculated digest value, or null if this
* reference has not been validated yet. Each invocation of this method
* returns a new clone to protect against subsequent modification.
*/
byte[] getCalculatedDigestValue();
/**
* Validates this reference. This method verifies the digest of this
* reference.
*
* This method only validates the reference the first time it is
* invoked. On subsequent invocations, it returns a cached result.
*
* @return true if this reference was validated successfully;
* false otherwise
* @param validateContext the validating context
* @throws NullPointerException if validateContext is
* null
* @throws XMLSignatureException if an unexpected exception occurs while
* validating the reference
*/
boolean validate(XMLValidateContext validateContext)
throws XMLSignatureException;
/**
* Returns the dereferenced data, if
* reference caching
* is enabled. This is the result of dereferencing the URI of this
* reference during a validation or generation operation.
*
* @return the dereferenced data, or null if reference
* caching is not enabled or this reference has not been generated or
* validated
*/
Data getDereferencedData();
/**
* Returns the pre-digested input stream, if
* reference caching
* is enabled. This is the input to the digest operation during a
* validation or signing operation.
*
* @return an input stream containing the pre-digested input, or
* null if reference caching is not enabled or this
* reference has not been generated or validated
*/
InputStream getDigestInputStream();
}