com.helger.xml.serialize.write.IXMLWriterSettings Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-xml Show documentation
Java 1.8+ Library with XML handling routines
There is a newer version: 11.1.8
/*
 * Copyright (C) 2014-2023 Philip Helger (www.helger.com)
 * philip[at]helger[dot]com
 *
 * Licensed 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.
 */
package com.helger.xml.serialize.write;

import java.nio.charset.Charset;

import javax.annotation.Nonnull;
import javax.xml.namespace.NamespaceContext;

import com.helger.commons.annotation.Nonempty;
import com.helger.commons.system.ENewLineMode;
import com.helger.xml.EXMLVersion;

/**
 * Interface for the settings to be used for serializing XML nodes.
 *
 * @author Philip Helger
 */
public interface IXMLWriterSettings
{
  /**
   * @return The XML version to use. Default is 1.0
   */
  @Nonnull
  EXMLVersion getXMLVersion ();

  /**
   * @return The XML serialize version to use. Default is XML 1.0
   */
  @Nonnull
  EXMLSerializeVersion getSerializeVersion ();

  /**
   * @return Write XML declaration? Default is true.
   */
  @Nonnull
  EXMLSerializeXMLDeclaration getSerializeXMLDeclaration ();

  /**
   * @return true if a newline should be added after the XML
   *         declaration or not. Defaults to true.
   * @since 9.3.5
   */
  boolean isNewLineAfterXMLDeclaration ();

  /**
   * @return Write document type? Default is true.
   */
  @Nonnull
  EXMLSerializeDocType getSerializeDocType ();

  /**
   * @return Write comments? Default is true.
   */
  @Nonnull
  EXMLSerializeComments getSerializeComments ();

  /**
   * @return Indent and/or align code? Default is
   *         indent and aligned.
   */
  @Nonnull
  EXMLSerializeIndent getIndent ();

  /**
   * @return The dynamic (per-element) indentation determinator. This must be
   *         changed when e.g. serializing HTML. Never null.
   */
  @Nonnull
  IXMLIndentDeterminator getIndentDeterminator ();

  /**
   * @return The incorrect character handling to be used. May not be
   *         null.
   */
  @Nonnull
  EXMLIncorrectCharacterHandling getIncorrectCharacterHandling ();

  /**
   * @return The charset to use. May never be null.
   */
  @Nonnull
  Charset getCharset ();

  /**
   * @return The namespace context to be used. Never null.
   */
  @Nonnull
  NamespaceContext getNamespaceContext ();

  /**
   * @return true if attribute values should be enclosed in double
   *         quotes, false if single quotes should be used.
   */
  boolean isUseDoubleQuotesForAttributes ();

  /**
   * @return The dynamic (per-element) bracket mode determinator to use. This
   *         must be changed when e.g. serializing HTML. Never null
   *         .
   */
  @Nonnull
  IXMLBracketModeDeterminator getBracketModeDeterminator ();

  /**
   * Determine if a self closed element (an element having no children) should
   * be emitted with a space at the end (<br />) or not (
   * <br/>)
   *
   * @return true if a space should be emitted, false
   *         if no space should be emitted.
   */
  boolean isSpaceOnSelfClosedElement ();

  /**
   * @return The newline mode to be used. By default it is the platform specific
   *         new line mode. Never null.
   */
  @Nonnull
  ENewLineMode getNewLineMode ();

  /**
   * @return The string representing the new line mode. A shortcut for
   *         getNewLineMode ().getText().
   */
  @Nonnull
  @Nonempty
  default String getNewLineString ()
  {
    return getNewLineMode ().getText ();
  }

  /**
   * @return The string to be used for indentation of a single level. By default
   *         it is 2 spaces.
   */
  @Nonnull
  @Nonempty
  String getIndentationString ();

  /**
   * Determine if namespaces should be emitted or not.
   *
   * @return true if namespaces should be emitted,
   *         false if all created elements should reside in the
   *         default namespace.
   */
  boolean isEmitNamespaces ();

  /**
   * Check if the flag for putting all namespace prefixes specified in the
   * namespace context should be put in the root document. This setting only has
   * an effect if a namespace context is defined and if it implements the
   * {@link com.helger.xml.namespace.IIterableNamespaceContext} interface!
   *
   * @return true if it is enabled, false if not.
   */
  boolean isPutNamespaceContextPrefixesInRoot ();

  /**
   * Check if all CDATA children should be emitted as normal text or not. This
   * is required for XML canonicalization.
   *
   * @return true if CDATA should be written as text,
   *         false to keep CDATA as it is.
   * @since 9.1.4
   */
  boolean isWriteCDATAAsText ();

  /**
   * Determine if attributes of elements and namespaces should be emitted in
   * alphabetical order or not. This is required for XML canonicalization.
   *
   * @return true to order attributes, false to keep
   *         the original order.
   * @since 9.1.4
   */
  boolean isOrderAttributesAndNamespaces ();
}