/*
 * This library is part of OpenCms -
 * the Open Source Content Management System
 *
 * Copyright (c) Alkacon Software GmbH & Co. KG (https://www.alkacon.com)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * For further information about Alkacon Software GmbH & Co. KG, please see the
 * company website: https://www.alkacon.com
 *
 * For further information about OpenCms, please see the
 * project website: https://www.opencms.org
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.opencms.xml.content;

import org.opencms.file.CmsFile;
import org.opencms.file.CmsObject;
import org.opencms.file.CmsProperty;
import org.opencms.file.CmsResource;
import org.opencms.i18n.CmsMessages;
import org.opencms.i18n.CmsMultiMessages.I_KeyFallbackHandler;
import org.opencms.main.CmsException;
import org.opencms.relations.CmsRelationType;
import org.opencms.search.fields.CmsSearchField;
import org.opencms.util.CmsDefaultSet;
import org.opencms.widgets.I_CmsComplexWidget;
import org.opencms.widgets.I_CmsWidget;
import org.opencms.workplace.editors.directedit.I_CmsEditHandler;
import org.opencms.xml.CmsXmlContentDefinition;
import org.opencms.xml.CmsXmlException;
import org.opencms.xml.containerpage.CmsFormatterConfiguration;
import org.opencms.xml.content.CmsDefaultXmlContentHandler.InvalidRelationAction;
import org.opencms.xml.types.I_CmsXmlContentValue;
import org.opencms.xml.types.I_CmsXmlContentValue.CmsSearchContentConfig;
import org.opencms.xml.types.I_CmsXmlContentValue.SearchContentType;
import org.opencms.xml.types.I_CmsXmlSchemaType;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Set;

import org.dom4j.Element;

import jakarta.servlet.ServletRequest;

/**
 * Handles special XML content livetime events, and also provides XML content editor rendering hints.<p>
 *
 * @since 6.0.0
 */
public interface I_CmsXmlContentHandler {

    /**
     * The available display types for element widgets.
     */
    public static enum DisplayType {
        /** The two column type. */
        column,

        /** The default display type. */
        none,

        /** The single line type. */
        singleline,

        /** The default wide display type. */
        wide
    }

    /**
     * Settings for a JSON renderer.
     */
    public static class JsonRendererSettings {

        /** The renderer class name. */
        private String m_className;

        /** The parameters for the renderer. */
        private Map<String, String> m_params;

        /**
         * Creates a new instance.
         *
         * @param className the class name
         * @param params the parameters
         */
        public JsonRendererSettings(String className, Map<String, String> params) {

            m_className = className;
            m_params = params;
        }

        /**
         * Gets the class name.
         *
         * @return the class name
         */
        public String getClassName() {

            return m_className;
        }

        /**
         * Gets the parameters.
         *
         * @return the parameters
         */
        public Map<String, String> getParameters() {

            if (m_params == null) {
                return Collections.emptyMap();
            }
            return Collections.unmodifiableMap(m_params);
        }
    }

    /**
     * The available mapping types. Currently only available for searchsettings (using the "addto" attribute in the node &lt;solrfield&gt;).
     */
    public static enum MappingType {
        /** Map for the content's resource. */
        ELEMENT,

        /** Map for all container pages the content is placed on. */
        PAGE
    }

    /** Represents how values should be handled with regard to synchronization across locales in the editor. */
    public static enum SynchronizationMode {
        /** No synchronization. */
        none,
        /** Normal synchronization. */
        standard,
        /** Strong synchronization - a value will be synchronized even if the parent nodes are missing in the target locale. */
        strong;
    }

    /** Mapping name for the 'date expired' mapping. */
    String ATTRIBUTE_DATEEXPIRED = "dateexpired";

    /** Mapping name for the 'date released' mapping. */
    String ATTRIBUTE_DATERELEASED = "datereleased";

    /** List of all allowed attribute mapping names, for fast lookup. */
    List<String> ATTRIBUTES = Collections.unmodifiableList(
        Arrays.asList(new String[] {ATTRIBUTE_DATERELEASED, ATTRIBUTE_DATEEXPIRED}));

    /** Prefix for attribute mappings. */
    String MAPTO_ATTRIBUTE = "attribute:";

    /** Prefix for permission mappings. */
    String MAPTO_PERMISSION = "permission:";

    /** Prefix for property mappings. */
    String MAPTO_PROPERTY = "property:";

    /** Prefix for property mappings. */
    String MAPTO_PROPERTY_INDIVIDUAL = MAPTO_PROPERTY + CmsProperty.TYPE_INDIVIDUAL + ":";

    /** Prefix for property list mappings. */
    String MAPTO_PROPERTY_LIST = "propertyList:";

    /** Prefix for property list mappings. */
    String MAPTO_PROPERTY_LIST_INDIVIDUAL = MAPTO_PROPERTY_LIST + CmsProperty.TYPE_INDIVIDUAL + ":";

    /** Prefix for property list mappings. */
    String MAPTO_PROPERTY_LIST_SHARED = MAPTO_PROPERTY_LIST + CmsProperty.TYPE_SHARED + ":";

    /** Prefix for property mappings. */
    String MAPTO_PROPERTY_SHARED = MAPTO_PROPERTY + CmsProperty.TYPE_SHARED + ":";

    /** Prefix for URL name mappings. */
    String MAPTO_URLNAME = "urlName";

    /**
     * Returns a (possibly empty set) of tags for the given field path (relative to the current content definition).
     *
     * <p>This is meant to provide metadata about a field for tools that process the content (e.g. translation).
     *
     * @param remainingPath path of a content field
     * @return the set of agent tags
     */
    public Set<String> getAgentTags(String remainingPath);

    /**
     * Gets the configured placeholder for the given path.
     *
     * @param path the element path
     * @return the placeholder (may contain macros)
     */
    public String getPlaceholder(String path);

    /**
     * Writes an availability date back to the content, if a mapping is defined for it.
     *
     * @param cms the CMS context
     * @param content the content to write to
     * @param attr the attribute to write
     * @param locales the locales of the resource
     * @param value the value to write
     *
     * @throws CmsException if something goes wrong
     */
    boolean applyReverseAvailabilityMapping(
        CmsObject cms,
        CmsXmlContent content,
        CmsMappingResolutionContext.AttributeType attr,
        List<Locale> locales,
        long value)
    throws CmsException;

    /**
     * Checks if an availability attribute should be written back to the content if the availability is changed through the availability dialog.
     *
     * @param attr the attribute to check
     * @return true if the attribute should be written to the content
     */
    boolean canUseReverseAvailabilityMapping(CmsMappingResolutionContext.AttributeType attr);

    /**
     * Removes potentially existing formerly mapped values, according
     * to the rules of the specific XML content handler.<p>
     *
     * The default implementation does nothing and is only added for backward compatibility.
     *
     * @param cms the current OpenCms user context
     * @param content the XML content to resolve the mappings for
     *
     * @throws CmsException if something goes wrong
     */
    @SuppressWarnings("unused")
    default void clearMappings(CmsObject cms, CmsXmlContent content) throws CmsException {

        // Do nothing by default.
        return;
    }

    /**
     * Gets the list of allowed template context names.<p>
     *
     * @return the list of allowed template context names
     */
    CmsDefaultSet<String> getAllowedTemplates();

    /**
     * Gets the list of change handler configurations.
     *
     * @return the list of change handler configurations
     */
    List<CmsChangeHandlerConfig> getChangeHandlerConfigs();

    /**
     * Gets the unconfigured complex widget defined for the given path.<p>
     *
     * @param cms the CMS context
     * @param path the value path
     * @return the complex widget
     */
    I_CmsComplexWidget getComplexWidget(CmsObject cms, String path);

    /**
     * Returns the configuration String value for the widget used to edit the given XML content schema type.<p>
     *
     * If no configuration value is available, this method must return <code>null</code>.
     *
     * @param type the value to get the widget configuration for
     *
     * @return the configuration String value for the widget used to edit the given XML content schema type
     */
    String getConfiguration(I_CmsXmlSchemaType type);

    /**
     * Gets the widget configuration for the given sub-path.<p>
     *
     * @param remainingPath a sub-path
     * @return the widget configuration for the given sub-path
     */
    String getConfiguration(String remainingPath);

    /**
     * Gets the configured display type for a given path.<p>
     *
     * @param path the path
     * @param defaultVal the value to return if no configured display type is found
     *
     * @return the configured display type (or the default value)
     */
    DisplayType getConfiguredDisplayType(String path, DisplayType defaultVal);

    /**
     * Returns the resource-independent CSS resources to include into the html-page head.<p>
     *
     * @return the CSS resources to include into the html-page head
     */
    Set<String> getCSSHeadIncludes();

    /**
     * Returns all the CSS resources to include into the html-page head.<p>
     *
     * @param cms the current CMS context
     * @param resource the resource from which to get the head includes
     *
     * @throws CmsException if something goes wrong
     *
     * @return the CSS resources to include into the html-page head
     */
    Set<String> getCSSHeadIncludes(CmsObject cms, CmsResource resource) throws CmsException;

    /**
     * Returns the default String value for the given XML content schema type object in the given XML content.<p>
     *
     * If a schema type does not have a default value, this method must return <code>null</code>.
     *
     * @param cms the current users OpenCms context
     * @param resource the content resource
     * @param type the type to get the default for
     * @param path the element path
     * @param locale the currently selected locale for the value
     *
     * @return the default String value for the given XML content value object
     *
     * @see org.opencms.xml.types.I_CmsXmlSchemaType#getDefault(Locale)
     */
    String getDefault(CmsObject cms, CmsResource resource, I_CmsXmlSchemaType type, String path, Locale locale);

    /**
     * Returns the default String value for the given XML content schema type object in the given XML content.<p>
     *
     * If a schema type does not have a default value, this method must return <code>null</code>.
     *
     * @param cms the current users OpenCms context
     * @param value the value to get the default for
     * @param locale the currently selected locale for the value
     *
     * @return the default String value for the given XML content value object
     *
     * @see org.opencms.xml.types.I_CmsXmlSchemaType#getDefault(Locale)
     */
    String getDefault(CmsObject cms, I_CmsXmlContentValue value, Locale locale);

    /**
     * Gets the default complex widget to be used for this type.<p>
     *
     * @return the default complex widget for this type
     */
    I_CmsComplexWidget getDefaultComplexWidget();

    /**
     * Gets the default complex widget class name configured for this type.<p>
     *
     * @return the default complex widget class name
     */
    String getDefaultComplexWidgetClass();

    /**
     * Gets the default complex widget configuration string configured for this type.<p>
     *
     * @return the default complex widget configuration string
     */
    String getDefaultComplexWidgetConfiguration();

    /**
     * Returns if the widget for this type should be displayed in compact view.<p>
     *
     * @param type the value to check the view mode for
     *
     * @return the widgets display type
     */
    DisplayType getDisplayType(I_CmsXmlSchemaType type);

    /**
     * Returns the edit handler if configured.<p>
     *
     * @return the edit handler
     */
    I_CmsEditHandler getEditHandler();

    /**
     * Returns the editor change handlers.<p>
     *
     * @param selfOnly if true, only return editor change handlers configured directly for this content handler
     * @return the editor change handlers
     */
    List<I_CmsXmlContentEditorChangeHandler> getEditorChangeHandlers(boolean selfOnly);

    /**
     * Returns the container page element formatter configuration for a given resource.<p>
     *
     * @param cms the current users OpenCms context, used for selecting the right project
     * @param res the resource for which the formatter configuration should be retrieved
     *
     * @return the container page element formatter configuration for this handler
     */
    CmsFormatterConfiguration getFormatterConfiguration(CmsObject cms, CmsResource res);

    /**
     * Gets the geo-coordinate mapping configuration.
     *
     * @return the geo-coordinate mapping configuration
     */
    CmsGeoMappingConfiguration getGeoMappingConfiguration();

    /**
     * Gets the action to perform if the given name refers to a link field which refers to a VFS file that no longer exists.
     *
     * @param name the field name
     * @return the action
     */
    default InvalidRelationAction getInvalidRelationAction(String name) {

        return null;
    }

    /**
     * Returns the resource-independent javascript resources to include into the html-page head.<p>
     *
     * @return the javascript resources to include into the html-page head
     */
    Set<String> getJSHeadIncludes();

    /**
     * Returns all the javascript resources to include into the html-page head.<p>
     *
     * @param cms the current CMS context
     * @param resource the resource for which the head includes should be retrieved
     *
     * @return the javascript resources to include into the html-page head
     *
     * @throws CmsException if something goes wrong
     */
    Set<String> getJSHeadIncludes(CmsObject cms, CmsResource resource) throws CmsException;

    /**
     * Gets the JSON renderer settings.
     *
     * @return the JSON renderer settings
     */
    JsonRendererSettings getJsonRendererSettings();

    /**
     * Gets the mappings defined in the schema.
     *
     * @return the mappings
     */
    Map<String, List<String>> getMappings();

    /**
     * Returns the all mappings defined for the given element xpath.<p>
     *
     * @param elementName the element xpath to look up the mapping for
     *
     * @return the mapping defined for the given element xpath
     */
    List<String> getMappings(String elementName);

    /**
     * Gets the message key fallback handler.<p>
     *
     * This is used to automatically provide fallbacks for missing message keys in the editor.<p>
     *
     * @return the message key fallback handler
     */
    I_KeyFallbackHandler getMessageKeyHandler();

    /**
     * Returns the {@link CmsMessages} that are used to resolve localized keys
     * for the given locale in this content handler.<p>
     *
     * If no localized messages are configured for this content handler,
     * this method returns <code>null</code>.<p>
     *
     * @param locale the locale to get the messages for
     *
     * @return the {@link CmsMessages} that are used to resolve localized keys
     * for the given locale in this content handler
     */
    CmsMessages getMessages(Locale locale);

    /**
     * Returns the folder name that contains eventual XML content model files to use for this resource type.<p>
     *
     * @return the folder name containing eventual XML content master files
     */
    String getModelFolder();

    /**
     * Returns the nested formatters for the given resource.<p>
     *
     * @param cms the cms context
     * @param res the resource
     * @param locale the content locale
     * @param req the request if available
     *
     * @return the nested formatter ids
     */
    List<String> getNestedFormatters(CmsObject cms, CmsResource res, Locale locale, ServletRequest req);

    /**
    * Gets the parameter with the given name..<p>
    *
    * @param param the parameter name
    * @return the parameter value
    */
    String getParameter(String param);

    /**
     * Returns the preview URI for the given XML content value object to be displayed in the editor.<p>
     *
     * If <code>null</code> is returned, no preview is possible for contents using this handler.<p>
     *
     * @param cms the current OpenCms user context
     * @param content the XML content to display the preview URI for
     * @param resourcename the name in the VFS of the resource that is currently edited
     *
     * @return the preview URI for the given XML content value object to be displayed in the editor
     */
    String getPreview(CmsObject cms, CmsXmlContent content, String resourcename);

    /**
     * Returns the relation type for the given value.<p>
     *
     * @param value the value to get the relation type for
     *
     * @return the relation type for the given value
     *
     * @deprecated use {@link #getRelationType(String)} with {@link I_CmsXmlContentValue#getPath()} instead
     */
    @Deprecated
    CmsRelationType getRelationType(I_CmsXmlContentValue value);

    /**
     * Returns the relation type for the given path.<p>
     *
     * @param path the path to get the relation type for
     *
     * @return the relation type for the given path
     */
    CmsRelationType getRelationType(String path);

    /**
     * Returns the relation type for the given path.<p>
     *
     * @param xpath the path to get the relation type for
     * @param defaultType the default type if none is set
     *
     * @return the relation type for the given path
     */
    CmsRelationType getRelationType(String xpath, CmsRelationType defaultType);

    /**
     * Returns the search content configuration, ie., the way how to integrate the value into full text search.<p>
     *
     * For the full text search, the value of all elements in one locale of the XML content are combined
     * to one big text, which is referred to as the "content" in the context of the full text search.
     * With this option, it is possible to hide certain elements from this "content" that does not make sense
     * to include in the full text search.<p>
     *
     * Moreover, if the value contains a link to another resource, the content of that other resource can be added.
     *
     * And additionally it is possible to adjust the value by a custom adjustment implementation before it is added.
     *
     * @param value the XML content value to check
     *
     * @return the search content type, indicating how the element should be added to the content for the full text search
     */
    CmsSearchContentConfig getSearchContentConfig(I_CmsXmlContentValue value);

    /**
     * Returns all configured Search fields for this XML content.<p>
     *
     * @return the Search fields for this XMl content
     */
    Set<CmsSearchField> getSearchFields();

    /**
     * Returns all configured Search fields for this XML content that should be attached to container pages the content is placed on.<p>
     *
     * @return the Search fields for this XMl content
     */
    Set<CmsSearchField> getSearchFieldsForPage();

    /**
     * Returns the search content settings defined in the annotation node of this XML content.<p>
     *
     * A search setting defined within the xsd:annotaion node of an XML schema definition can look like:<p>
     * <code>&lt;searchsetting element="Image/Align" searchContent="false"/&gt;</code><p>
     *
     * The returned map contains the 'element' attribute value as keys and the 'searchContent'
     * attribute value as values.<p>
     *
     * @return the search field settings for this XML content schema
     */
    Map<String, CmsSearchContentConfig> getSearchSettings();

    /**
     * Returns the element settings defined for the container page formatters.<p>
     *
     * @param cms the current CMS context
     * @param resource the resource for which to get the setting definitions
     *
     * @return the element settings defined for the container page formatters
     */
    Map<String, CmsXmlContentProperty> getSettings(CmsObject cms, CmsResource resource);

    /**
     * Returns the configuration for elements that require a synchronization across all locales.<p>
     *
     * @param recursive if true, recursively combines all synchronization information from nested schemas, otherwise only returns the synchronizations for this schema
     * @return the synchronization information
     */
    CmsSynchronizationSpec getSynchronizations(boolean recursive);

    /**
     * Returns the tabs to be displayed in the editor.<p>
     *
     * @return the tabs to be displayed in the editor
     */
    List<CmsXmlContentTab> getTabs();

    /**
     * Returns the "Title" mapping set for the given XML content document in the given Locale.<p>
     *
     * @param cms the current OpenCms user context
     * @param document the XML content to get the title mapping for (this must be of a type that uses this handler)
     * @param locale the locale to get the title mapping for
     *
     * @return the "Title" mapping set for the given XML content document in the given Locale
     */
    String getTitleMapping(CmsObject cms, CmsXmlContent document, Locale locale);

    /**
     * Gets the version transformation VFS path.
     *
     * <p>If schema versions are used, the the XSLT transformation read from this VFS path is used to transform contents
     * of older versions into the current version.
     *
     * @return the VFS path to read an XSLT file for version transformation from
     */
    String getVersionTransformation();

    /**
     * Gets the widget for the given path and CMS context.
     *
     * @param cms the current CMS context
     * @param path the XML value path
     * @return the widget for the path
     */
    I_CmsWidget getWidget(CmsObject cms, String path);

    /**
     * Returns the editor widget that should be used for the given XML content value.<p>
     *
     * The handler implementations should use the "appinfo" node of the XML content definition
     * schema to define the mappings of elements to widgets.<p>
     *
     * @param value the XML content value to get the widget for
     *
     * @return the editor widget that should be used for the given XML content value
     *
     * @throws CmsXmlException if something goes wrong
     */
    @Deprecated
    I_CmsWidget getWidget(I_CmsXmlSchemaType value) throws CmsXmlException;

    /**
     * Returns true if the contents for this content handler have schema-based formatters which can be disabled or enabled.<p>
     *
     * @return true if the contents for this content handler have schema-based formatters which can be disabled or enabled
     */
    boolean hasModifiableFormatters();

    /**
     * Returns whether there are nested formatters configured for this content type.<p>
     *
     * @return <code>true</code> if there are nested formatters configured for this content type
     */
    boolean hasNestedFormatters();

    /**
     * Returns if there are locale synchronized elements configured.<p>
     *
     * @return <code>true</code> if there are locale synchronized elements configured
     */
    boolean hasSynchronizedElements();

    /**
     * Returns if there are visibility handlers configured for this content type.<p>
     *
     * @return <code>true</code> if there are visibility handlers configured for this content type
     */
    boolean hasVisibilityHandlers();

    /**
     * Initializes this content handler for the given XML content definition by
     * analyzing the "appinfo" node.<p>
     *
     * @param appInfoElement the "appinfo" element root node to analyze
     * @param contentDefinition the XML content definition that XML content handler belongs to
     *
     * @throws CmsXmlException if something goes wrong
     */
    void initialize(Element appInfoElement, CmsXmlContentDefinition contentDefinition) throws CmsXmlException;

    /**
     * Performs a check of the given XML document.<p>
     *
     * The main difference to the {@link #resolveValidation(CmsObject, I_CmsXmlContentValue, CmsXmlContentErrorHandler)}
     * method is that this method may silently remove some values, for instance, for broken links.<p>
     *
     * @param cms the current OpenCms user context
     * @param document the document to resolve the check rules for
     */
    void invalidateBrokenLinks(CmsObject cms, CmsXmlContent document);

    /**
     * Checks whether the Acacia editor is disabled for this type.<p>
     *
     * @return true if the Acacia editor is disabled
     */
    boolean isAcaciaEditorDisabled();

    /**
     * Returns <code>true</code> if the XML content should be indexed when it is dropped in a container page,
     * and returns <code>false</code> if this XML content should be indexed as 'stand-alone' document.<p>
     *
     * This flag is intended by excluding XML contents from the search index that are not used as detail pages,
     * but to index those extraction result when they are part of a container page.<p>
     *
     * In order to set this falg add an attribute <code>containerpageOnly="true"</code> to the
     * <code>'&lt;searchsettings&gt;-node'</code> of the XSD of the resource type you want to be indexed only
     * when it is part of a container page.<p>
     *
     * @return the container page only flag
     */
    boolean isContainerPageOnly();

    /**
     * Returns <code>true</code> in case the given value should be searchable with
     * the integrated full text search.<p>
     *
     * For the full text search, the value of all elements in one locale of the XML content are combined
     * to one big text, which is referred to as the "content" in the context of the full text search.
     * With this option, it is possible to hide certain elements from this "content" that does not make sense
     * to include in the full text search.<p>
     *
     * @param value the XML content value to check
     *
     * @return <code>true</code> in case the given value should be searchable
     *
     * @deprecated use {@link #getSearchContentConfig(I_CmsXmlContentValue)} instead. Will be removed if plain lucene search is removed.
     */
    @Deprecated
    default boolean isSearchable(I_CmsXmlContentValue value) {

        CmsSearchContentConfig config = getSearchContentConfig(value);
        return Objects.equals(null == config ? null : config.getSearchContentType(), SearchContentType.TRUE);
    }

    /**
     * Returns if the given content field should be visible to the current user.<p>
     *
     * @param cms the cms context
     * @param schemaType the content value type
     * @param valuePath the value path
     * @param resource the edited resource
     * @param contentLocale the content locale
     *
     * @return <code>true</code> if the given content field should be visible to the current user
     */
    boolean isVisible(
        CmsObject cms,
        I_CmsXmlSchemaType schemaType,
        String valuePath,
        CmsResource resource,
        Locale contentLocale);

    /**
     * Prepares the given XML content to be used after it was read from the OpenCms VFS.<p>
     *
     * This method is always called after any content is unmarshalled.
     * It can be used to perform customized actions on the given XML content.<p>
     *
     * @param cms the current OpenCms user context
     * @param content the XML content to be used as read from the VFS
     *
     * @return the prepared content to be used
     */
    CmsXmlContent prepareForUse(CmsObject cms, CmsXmlContent content);

    /**
     * Prepares the given XML content to be written to the OpenCms VFS.<p>
     *
     * This method is always called before any content gets written.
     * It can be used to perform XML validation, pretty - printing
     * or customized actions on the given XML content.<p>
     *
     * @param cms the current OpenCms user context
     * @param content the XML content to be written
     * @param file the resource the XML content in it's current state was unmarshalled from
     *
     * @return the file to write to the OpenCms VFS, this will be an updated version of the parameter file
     *
     * @throws CmsException in case something goes wrong
     */
    CmsFile prepareForWrite(CmsObject cms, CmsXmlContent content, CmsFile file) throws CmsException;

    /**
     * Resolves the value mappings of the given XML content value, according
     * to the rules of this XML content handler.<p>
     *
     * @param cms the current OpenCms user context
     * @param content the XML content to resolve the mappings for
     * @param value the value to resolve the mappings for
     *
     * @throws CmsException if something goes wrong
     */
    void resolveMapping(CmsObject cms, CmsXmlContent content, I_CmsXmlContentValue value) throws CmsException;

    /**
     * Performs a validation of the given XML content value, and saves all errors or warnings found in
     * the provided XML content error handler.<p>
     *
     * The errorHandler parameter is optional, if <code>null</code> is given a new error handler
     * instance must be created.<p>
     *
     * @param cms the current OpenCms user context
     * @param value the value to resolve the validation rules for
     * @param errorHandler (optional) an error handler instance that contains previous error or warnings
     *
     * @return an error handler that contains all errors and warnings currently found
     */
    CmsXmlContentErrorHandler resolveValidation(
        CmsObject cms,
        I_CmsXmlContentValue value,
        CmsXmlContentErrorHandler errorHandler);

}