1 /*

     2  * reserved comment block

     3  * DO NOT REMOVE OR ALTER!

     4  */

     5 /**

     6  * Licensed to the Apache Software Foundation (ASF) under one

     7  * or more contributor license agreements. See the NOTICE file

     8  * distributed with this work for additional information

     9  * regarding copyright ownership. The ASF licenses this file

    10  * to you under the Apache License, Version 2.0 (the

    11  * "License"); you may not use this file except in compliance

    12  * with the License. You may obtain a copy of the License at

    13  *

    14  * http://www.apache.org/licenses/LICENSE-2.0

    15  *

    16  * Unless required by applicable law or agreed to in writing,

    17  * software distributed under the License is distributed on an

    18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

    19  * KIND, either express or implied. See the License for the

    20  * specific language governing permissions and limitations

    21  * under the License.

    22  */

    23 package org.jcp.xml.dsig.internal.dom;

    24 

    25 import javax.xml.crypto.MarshalException;

    26 import javax.xml.crypto.XMLCryptoContext;

    27 import javax.xml.crypto.XMLStructure;

    28 

    29 import org.w3c.dom.Attr;

    30 

    31 /**

    32  * This interface is used to construct XML via a sequence of API calls.

    33  *

    34  * <p>This is written to be similar to javax.xml.stream.XMLStreamWriter, but

    35  * has slightly different requirements. Specifically, we need to be able to create

    36  * an "ID" type attribute, and get the current node.

    37  * </p>

    38  */

    39 public interface XmlWriter {

    40 

    41     /**

    42      * Utility class that brings together the class, and the method for marshaling an

    43      * instance of said class.

    44      *

    45      * @param <CLZ>

    46      */

    47     abstract static class ToMarshal<CLZ extends XMLStructure> { //NOPMD

    48         public final Class<CLZ> clazzToMatch;

    49 

    50         public ToMarshal(Class<CLZ> clazzToMatch) {

    51             this.clazzToMatch = clazzToMatch;

    52         }

    53 

    54         public abstract void marshalObject(XmlWriter xwriter, CLZ toMarshal, String dsPrefix,

    55                 XMLCryptoContext context) throws MarshalException;

    56     }

    57 

    58     /**

    59      *

    60      * @param prefix    What prefix to use?

    61      * @param localName What local name to use?

    62      * @param namespaceURI  What namespace URI?

    63      *

    64      * See also {@link javax.xml.stream.XMLStreamWriter#writeStartElement(String, String, String)}

    65      */

    66     void writeStartElement(String prefix, String localName, String namespaceURI);

    67 

    68     /**

    69      * See also {@link javax.xml.stream.XMLStreamWriter#writeEndElement()}

    70      */

    71     void writeEndElement();

    72 

    73     /**

    74      * Convenience method that writes both a start and end tag, with text contents as

    75      * provided.

    76      *

    77      * @param prefix

    78      * @param localName

    79      * @param namespaceURI

    80      * @param value

    81      */

    82     void writeTextElement(String prefix, String localName, String namespaceURI, String value);

    83 

    84     void writeNamespace(String prefix, String namespaceURI);

    85 

    86     void writeCharacters(String text);

    87 

    88     void writeComment(String text);

    89 

    90     Attr writeAttribute(String prefix, String namespaceURI, String localName, String value);

    91 

    92     void writeIdAttribute(String prefix, String namespaceURI, String localName, String value);

    93 

    94     /**

    95      * Get the local name of the current element.

    96      * @return the local name of the current element.

    97      */

    98     String getCurrentLocalName();

    99 

   100     XMLStructure getCurrentNodeAsStructure();

   101 

   102     /**

   103      * This method marshals a structure, and relies on implementation specific details for how

   104      * an instance of a particular class maps to the method that actually does the marshaling.

   105      *

   106      * @param toMarshal The object to be marshaled.

   107      * @param dsPrefix  The digital signature prefix.

   108      * @param context   The context for marshaling.

   109      * @throws MarshalException Thrown if something goes wrong during the marshaling.

   110      */

   111     void marshalStructure(XMLStructure toMarshal, String dsPrefix, XMLCryptoContext context) throws MarshalException;

   112 }