com.helger.xml.serialize.read.IBaseXMLReaderSettings 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
The newest version!
/*
 * Copyright (C) 2014-2024 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.read;

import java.util.Locale;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import org.xml.sax.EntityResolver;
import org.xml.sax.ErrorHandler;

import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.annotation.ReturnsMutableObject;
import com.helger.commons.callback.CallbackList;
import com.helger.commons.callback.exception.IExceptionCallback;
import com.helger.commons.collection.impl.ICommonsMap;
import com.helger.xml.EXMLParserFeature;
import com.helger.xml.EXMLParserProperty;

/**
 * Base Read-only interface for DOM and SAX reader settings.
 *
 * @author Philip Helger
 */
public interface IBaseXMLReaderSettings
{
  /**
   * @return true if at least one parser property is defined
   */
  boolean hasAnyProperties ();

  /**
   * Get the value of the specified parser property
   *
   * @param eProperty
   *        The property to use. May be null.
   * @return null if no such property was found.
   */
  @Nullable
  Object getPropertyValue (@Nullable EXMLParserProperty eProperty);

  /**
   * @return A copy of all contained parser property values. Never
   *         null.
   */
  @Nonnull
  @ReturnsMutableCopy
  ICommonsMap  getAllPropertyValues ();

  /**
   * @return The locale to be used for error messages. By default it is
   *         null and therefore the XML parser will use the system
   *         default locale.
   */
  @Nullable
  Locale getLocale ();

  /**
   * @return true if at least one parser feature is defined,
   *         false if not
   */
  boolean hasAnyFeature ();

  /**
   * Get the value of the specified parser feature
   *
   * @param eFeature
   *        The feature to search. May be null.
   * @return null if this feature is undefined.
   */
  @Nullable
  Boolean getFeatureValue (@Nullable EXMLParserFeature eFeature);

  /**
   * @return A copy of all defined parser features at the associated values.
   */
  @Nonnull
  @ReturnsMutableCopy
  ICommonsMap  getAllFeatureValues ();

  /**
   * @return A special error handler to be used or null if no
   *         special error handler is needed.
   */
  @Nullable
  ErrorHandler getErrorHandler ();

  /**
   * @return The special entity resolver to be used. May be null.
   */
  @Nullable
  EntityResolver getEntityResolver ();

  /**
   * @return A special exception handler to be used. Never null.
   */
  @Nonnull
  @ReturnsMutableObject
  CallbackList > exceptionCallbacks ();

  /**
   * Check if the current settings require a separate DOM
   * {@link javax.xml.parsers.DocumentBuilderFactory}/SAX
   * {@link org.xml.sax.XMLReader} object or if a pooled default object can be
   * used.
   *
   * @return true if a separate parser object is required,
   *         false if not.
   */
  boolean requiresNewXMLParser ();
}