001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.xml.content;
029
030import org.opencms.file.CmsFile;
031import org.opencms.file.CmsObject;
032import org.opencms.file.CmsProperty;
033import org.opencms.file.CmsResource;
034import org.opencms.i18n.CmsMessages;
035import org.opencms.i18n.CmsMultiMessages.I_KeyFallbackHandler;
036import org.opencms.main.CmsException;
037import org.opencms.relations.CmsRelationType;
038import org.opencms.search.fields.CmsSearchField;
039import org.opencms.util.CmsDefaultSet;
040import org.opencms.widgets.I_CmsComplexWidget;
041import org.opencms.widgets.I_CmsWidget;
042import org.opencms.workplace.editors.directedit.I_CmsEditHandler;
043import org.opencms.xml.CmsXmlContentDefinition;
044import org.opencms.xml.CmsXmlException;
045import org.opencms.xml.containerpage.CmsFormatterConfiguration;
046import org.opencms.xml.content.CmsDefaultXmlContentHandler.InvalidRelationAction;
047import org.opencms.xml.types.I_CmsXmlContentValue;
048import org.opencms.xml.types.I_CmsXmlContentValue.SearchContentType;
049import org.opencms.xml.types.I_CmsXmlSchemaType;
050
051import java.util.Arrays;
052import java.util.Collections;
053import java.util.List;
054import java.util.Locale;
055import java.util.Map;
056import java.util.Objects;
057import java.util.Set;
058
059import javax.servlet.ServletRequest;
060
061import org.dom4j.Element;
062
063/**
064 * Handles special XML content livetime events, and also provides XML content editor rendering hints.<p>
065 *
066 * @since 6.0.0
067 */
068public interface I_CmsXmlContentHandler {
069
070    /**
071     * The available display types for element widgets.
072     */
073    public static enum DisplayType {
074        /** The two column type. */
075        column,
076
077        /** The default display type. */
078        none,
079
080        /** The single line type. */
081        singleline,
082
083        /** The default wide display type. */
084        wide
085    }
086
087    /**
088     * Settings for a JSON renderer.
089     */
090    public static class JsonRendererSettings {
091
092        /** The renderer class name. */
093        private String m_className;
094
095        /** The parameters for the renderer. */
096        private Map<String, String> m_params;
097
098        /**
099         * Creates a new instance.
100         *
101         * @param className the class name
102         * @param params the parameters
103         */
104        public JsonRendererSettings(String className, Map<String, String> params) {
105
106            m_className = className;
107            m_params = params;
108        }
109
110        /**
111         * Gets the class name.
112         *
113         * @return the class name
114         */
115        public String getClassName() {
116
117            return m_className;
118        }
119
120        /**
121         * Gets the parameters.
122         *
123         * @return the parameters
124         */
125        public Map<String, String> getParameters() {
126
127            if (m_params == null) {
128                return Collections.emptyMap();
129            }
130            return Collections.unmodifiableMap(m_params);
131        }
132
133    }
134
135    /**
136     * The available mapping types. Currently only available for searchsettings (using the "addto" attribute in the node &lt;solrfield&gt;).
137     */
138    public static enum MappingType {
139        /** Map for the content's resource. */
140        ELEMENT,
141
142        /** Map for all container pages the content is placed on. */
143        PAGE
144    }
145
146    /** Mapping name for the 'date expired' mapping. */
147    String ATTRIBUTE_DATEEXPIRED = "dateexpired";
148
149    /** Mapping name for the 'date released' mapping. */
150    String ATTRIBUTE_DATERELEASED = "datereleased";
151
152    /** List of all allowed attribute mapping names, for fast lookup. */
153    List<String> ATTRIBUTES = Collections.unmodifiableList(
154        Arrays.asList(new String[] {ATTRIBUTE_DATERELEASED, ATTRIBUTE_DATEEXPIRED}));
155
156    /** Prefix for attribute mappings. */
157    String MAPTO_ATTRIBUTE = "attribute:";
158
159    /** Prefix for permission mappings. */
160    String MAPTO_PERMISSION = "permission:";
161
162    /** Prefix for property mappings. */
163    String MAPTO_PROPERTY = "property:";
164
165    /** Prefix for property mappings. */
166    String MAPTO_PROPERTY_INDIVIDUAL = MAPTO_PROPERTY + CmsProperty.TYPE_INDIVIDUAL + ":";
167
168    /** Prefix for property list mappings. */
169    String MAPTO_PROPERTY_LIST = "propertyList:";
170
171    /** Prefix for property list mappings. */
172    String MAPTO_PROPERTY_LIST_INDIVIDUAL = MAPTO_PROPERTY_LIST + CmsProperty.TYPE_INDIVIDUAL + ":";
173
174    /** Prefix for property list mappings. */
175    String MAPTO_PROPERTY_LIST_SHARED = MAPTO_PROPERTY_LIST + CmsProperty.TYPE_SHARED + ":";
176
177    /** Prefix for property mappings. */
178    String MAPTO_PROPERTY_SHARED = MAPTO_PROPERTY + CmsProperty.TYPE_SHARED + ":";
179
180    /** Prefix for URL name mappings. */
181    String MAPTO_URLNAME = "urlName";
182
183    /**
184     * Writes an availability date back to the content, if a mapping is defined for it.
185     *
186     * @param cms the CMS context
187     * @param content the content to write to
188     * @param attr the attribute to write
189     * @param locales the locales of the resource
190     * @param value the value to write
191     *
192     * @throws CmsException if something goes wrong
193     */
194    boolean applyReverseAvailabilityMapping(
195        CmsObject cms,
196        CmsXmlContent content,
197        CmsMappingResolutionContext.AttributeType attr,
198        List<Locale> locales,
199        long value)
200    throws CmsException;
201
202    /**
203     * Checks if an availability attribute should be written back to the content if the availability is changed through the availability dialog.
204     *
205     * @param attr the attribute to check
206     * @return true if the attribute should be written to the content
207     */
208    boolean canUseReverseAvailabilityMapping(CmsMappingResolutionContext.AttributeType attr);
209
210    /**
211     * Gets the list of allowed template context names.<p>
212     *
213     * @return the list of allowed template context names
214     */
215    CmsDefaultSet<String> getAllowedTemplates();
216
217    /**
218     * Gets the list of change handler configurations.
219     *
220     * @return the list of change handler configurations
221     */
222    List<CmsChangeHandlerConfig> getChangeHandlerConfigs();
223
224    /**
225     * Gets the unconfigured complex widget defined for the given path.<p>
226     *
227     * @param cms the CMS context
228     * @param path the value path
229     * @return the complex widget
230     */
231    I_CmsComplexWidget getComplexWidget(CmsObject cms, String path);
232
233    /**
234     * Returns the configuration String value for the widget used to edit the given XML content schema type.<p>
235     *
236     * If no configuration value is available, this method must return <code>null</code>.
237     *
238     * @param type the value to get the widget configuration for
239     *
240     * @return the configuration String value for the widget used to edit the given XML content schema type
241     */
242    String getConfiguration(I_CmsXmlSchemaType type);
243
244    /**
245     * Gets the widget configuration for the given sub-path.<p>
246     *
247     * @param remainingPath a sub-path
248     * @return the widget configuration for the given sub-path
249     */
250    String getConfiguration(String remainingPath);
251
252    /**
253     * Gets the configured display type for a given path.<p>
254     *
255     * @param path the path
256     * @param defaultVal the value to return if no configured display type is found
257     *
258     * @return the configured display type (or the default value)
259     */
260    DisplayType getConfiguredDisplayType(String path, DisplayType defaultVal);
261
262    /**
263     * Returns the resource-independent CSS resources to include into the html-page head.<p>
264     *
265     * @return the CSS resources to include into the html-page head
266     */
267    Set<String> getCSSHeadIncludes();
268
269    /**
270     * Returns all the CSS resources to include into the html-page head.<p>
271     *
272     * @param cms the current CMS context
273     * @param resource the resource from which to get the head includes
274     *
275     * @throws CmsException if something goes wrong
276     *
277     * @return the CSS resources to include into the html-page head
278     */
279    Set<String> getCSSHeadIncludes(CmsObject cms, CmsResource resource) throws CmsException;
280
281    /**
282     * Returns the default String value for the given XML content schema type object in the given XML content.<p>
283     *
284     * If a schema type does not have a default value, this method must return <code>null</code>.
285     *
286     * @param cms the current users OpenCms context
287     * @param resource the content resource
288     * @param type the type to get the default for
289     * @param path the element path
290     * @param locale the currently selected locale for the value
291     *
292     * @return the default String value for the given XML content value object
293     *
294     * @see org.opencms.xml.types.I_CmsXmlSchemaType#getDefault(Locale)
295     */
296    String getDefault(CmsObject cms, CmsResource resource, I_CmsXmlSchemaType type, String path, Locale locale);
297
298    /**
299     * Returns the default String value for the given XML content schema type object in the given XML content.<p>
300     *
301     * If a schema type does not have a default value, this method must return <code>null</code>.
302     *
303     * @param cms the current users OpenCms context
304     * @param value the value to get the default for
305     * @param locale the currently selected locale for the value
306     *
307     * @return the default String value for the given XML content value object
308     *
309     * @see org.opencms.xml.types.I_CmsXmlSchemaType#getDefault(Locale)
310     */
311    String getDefault(CmsObject cms, I_CmsXmlContentValue value, Locale locale);
312
313    /**
314     * Gets the default complex widget to be used for this type.<p>
315     *
316     * @return the default complex widget for this type
317     */
318    I_CmsComplexWidget getDefaultComplexWidget();
319
320    /**
321     * Gets the default complex widget class name configured for this type.<p>
322     *
323     * @return the default complex widget class name
324     */
325    String getDefaultComplexWidgetClass();
326
327    /**
328     * Gets the default complex widget configuration string configured for this type.<p>
329     *
330     * @return the default complex widget configuration string
331     */
332    String getDefaultComplexWidgetConfiguration();
333
334    /**
335     * Returns if the widget for this type should be displayed in compact view.<p>
336     *
337     * @param type the value to check the view mode for
338     *
339     * @return the widgets display type
340     */
341    DisplayType getDisplayType(I_CmsXmlSchemaType type);
342
343    /**
344     * Returns the edit handler if configured.<p>
345     *
346     * @return the edit handler
347     */
348    I_CmsEditHandler getEditHandler();
349
350    /**
351     * Returns the editor change handlers.<p>
352     *
353     * @param selfOnly if true, only return editor change handlers configured directly for this content handler
354     * @return the editor change handlers
355     */
356    List<I_CmsXmlContentEditorChangeHandler> getEditorChangeHandlers(boolean selfOnly);
357
358    /**
359     * Returns the container page element formatter configuration for a given resource.<p>
360     *
361     * @param cms the current users OpenCms context, used for selecting the right project
362     * @param res the resource for which the formatter configuration should be retrieved
363     *
364     * @return the container page element formatter configuration for this handler
365     */
366    CmsFormatterConfiguration getFormatterConfiguration(CmsObject cms, CmsResource res);
367
368    /**
369     * Gets the geo-coordinate mapping configuration.
370     *
371     * @return the geo-coordinate mapping configuration
372     */
373    CmsGeoMappingConfiguration getGeoMappingConfiguration();
374
375    /**
376     * Gets the action to perform if the given name refers to a link field which refers to a VFS file that no longer exists.
377     *
378     * @param name the field name
379     * @return the action
380     */
381    default InvalidRelationAction getInvalidRelationAction(String name) {
382
383        return null;
384    }
385
386    /**
387     * Returns the resource-independent javascript resources to include into the html-page head.<p>
388     *
389     * @return the javascript resources to include into the html-page head
390     */
391    Set<String> getJSHeadIncludes();
392
393    /**
394     * Returns all the javascript resources to include into the html-page head.<p>
395     *
396     * @param cms the current CMS context
397     * @param resource the resource for which the head includes should be retrieved
398     *
399     * @return the javascript resources to include into the html-page head
400     *
401     * @throws CmsException if something goes wrong
402     */
403    Set<String> getJSHeadIncludes(CmsObject cms, CmsResource resource) throws CmsException;
404
405    /**
406     * Gets the JSON renderer settings.
407     *
408     * @return the JSON renderer settings
409     */
410    JsonRendererSettings getJsonRendererSettings();
411
412    /**
413     * Gets the mappings defined in the schema.
414     *
415     * @return the mappings
416     */
417    Map<String, List<String>> getMappings();
418
419    /**
420     * Returns the all mappings defined for the given element xpath.<p>
421     *
422     * @param elementName the element xpath to look up the mapping for
423     *
424     * @return the mapping defined for the given element xpath
425     */
426    List<String> getMappings(String elementName);
427
428    /**
429     * Gets the message key fallback handler.<p>
430     *
431     * This is used to automatically provide fallbacks for missing message keys in the editor.<p>
432     *
433     * @return the message key fallback handler
434     */
435    I_KeyFallbackHandler getMessageKeyHandler();
436
437    /**
438     * Returns the {@link CmsMessages} that are used to resolve localized keys
439     * for the given locale in this content handler.<p>
440     *
441     * If no localized messages are configured for this content handler,
442     * this method returns <code>null</code>.<p>
443     *
444     * @param locale the locale to get the messages for
445     *
446     * @return the {@link CmsMessages} that are used to resolve localized keys
447     * for the given locale in this content handler
448     */
449    CmsMessages getMessages(Locale locale);
450
451    /**
452     * Returns the folder name that contains eventual XML content model files to use for this resource type.<p>
453     *
454     * @return the folder name containing eventual XML content master files
455     */
456    String getModelFolder();
457
458    /**
459     * Returns the nested formatters for the given resource.<p>
460     *
461     * @param cms the cms context
462     * @param res the resource
463     * @param locale the content locale
464     * @param req the request if available
465     *
466     * @return the nested formatter ids
467     */
468    List<String> getNestedFormatters(CmsObject cms, CmsResource res, Locale locale, ServletRequest req);
469
470    /**
471    * Gets the parameter with the given name..<p>
472    *
473    * @param param the parameter name
474    * @return the parameter value
475    */
476    String getParameter(String param);
477
478    /**
479     * Returns the preview URI for the given XML content value object to be displayed in the editor.<p>
480     *
481     * If <code>null</code> is returned, no preview is possible for contents using this handler.<p>
482     *
483     * @param cms the current OpenCms user context
484     * @param content the XML content to display the preview URI for
485     * @param resourcename the name in the VFS of the resource that is currently edited
486     *
487     * @return the preview URI for the given XML content value object to be displayed in the editor
488     */
489    String getPreview(CmsObject cms, CmsXmlContent content, String resourcename);
490
491    /**
492     * Returns the relation type for the given value.<p>
493     *
494     * @param value the value to get the relation type for
495     *
496     * @return the relation type for the given value
497     *
498     * @deprecated use {@link #getRelationType(String)} with {@link I_CmsXmlContentValue#getPath()} instead
499     */
500    @Deprecated
501    CmsRelationType getRelationType(I_CmsXmlContentValue value);
502
503    /**
504     * Returns the relation type for the given path.<p>
505     *
506     * @param path the path to get the relation type for
507     *
508     * @return the relation type for the given path
509     */
510    CmsRelationType getRelationType(String path);
511
512    /**
513     * Returns the relation type for the given path.<p>
514     *
515     * @param xpath the path to get the relation type for
516     * @param defaultType the default type if none is set
517     *
518     * @return the relation type for the given path
519     */
520    CmsRelationType getRelationType(String xpath, CmsRelationType defaultType);
521
522    /**
523     * Returns the search content type, ie., the way how to integrate the value into full text search.<p>
524     *
525     * For the full text search, the value of all elements in one locale of the XML content are combined
526     * to one big text, which is referred to as the "content" in the context of the full text search.
527     * With this option, it is possible to hide certain elements from this "content" that does not make sense
528     * to include in the full text search.<p>
529     *
530     * Moreover, if the value contains a link to another resource, the content of that other resource can be added.
531     *
532     * @param value the XML content value to check
533     *
534     * @return the search content type, indicating how the element should be added to the content for the full text search
535     */
536    SearchContentType getSearchContentType(I_CmsXmlContentValue value);
537
538    /**
539     * Returns all configured Search fields for this XML content.<p>
540     *
541     * @return the Search fields for this XMl content
542     */
543    Set<CmsSearchField> getSearchFields();
544
545    /**
546     * Returns all configured Search fields for this XML content that should be attached to container pages the content is placed on.<p>
547     *
548     * @return the Search fields for this XMl content
549     */
550    Set<CmsSearchField> getSearchFieldsForPage();
551
552    /**
553     * Returns the search content settings defined in the annotation node of this XML content.<p>
554     *
555     * A search setting defined within the xsd:annotaion node of an XML schema definition can look like:<p>
556     * <code>&lt;searchsetting element="Image/Align" searchContent="false"/&gt;</code><p>
557     *
558     * The returned map contains the 'element' attribute value as keys and the 'searchContent'
559     * attribute value as values.<p>
560     *
561     * @return the search field settings for this XML content schema
562     */
563    Map<String, SearchContentType> getSearchSettings();
564
565    /**
566     * Returns the element settings defined for the container page formatters.<p>
567     *
568     * @param cms the current CMS context
569     * @param resource the resource for which to get the setting definitions
570     *
571     * @return the element settings defined for the container page formatters
572     */
573    Map<String, CmsXmlContentProperty> getSettings(CmsObject cms, CmsResource resource);
574
575    /**
576     * Returns the elements that require a synchronization across all locales.<p>
577     *
578     * @return the element paths
579     */
580    List<String> getSynchronizations();
581
582    /**
583     * Returns the tabs to be displayed in the editor.<p>
584     *
585     * @return the tabs to be displayed in the editor
586     */
587    List<CmsXmlContentTab> getTabs();
588
589    /**
590     * Returns the "Title" mapping set for the given XML content document in the given Locale.<p>
591     *
592     * @param cms the current OpenCms user context
593     * @param document the XML content to get the title mapping for (this must be of a type that uses this handler)
594     * @param locale the locale to get the title mapping for
595     *
596     * @return the "Title" mapping set for the given XML content document in the given Locale
597     */
598    String getTitleMapping(CmsObject cms, CmsXmlContent document, Locale locale);
599
600    /**
601     * Gets the version transformation VFS path.
602     *
603     * <p>If schema versions are used, the the XSLT transformation read from this VFS path is used to transform contents
604     * of older versions into the current version.
605     *
606     * @return the VFS path to read an XSLT file for version transformation from
607     */
608    String getVersionTransformation();
609
610    /**
611     * Gets the widget for the given path and CMS context.
612     *
613     * @param cms the current CMS context
614     * @param path the XML value path
615     * @return the widget for the path
616     */
617    I_CmsWidget getWidget(CmsObject cms, String path);
618
619    /**
620     * Returns the editor widget that should be used for the given XML content value.<p>
621     *
622     * The handler implementations should use the "appinfo" node of the XML content definition
623     * schema to define the mappings of elements to widgets.<p>
624     *
625     * @param value the XML content value to get the widget for
626     *
627     * @return the editor widget that should be used for the given XML content value
628     *
629     * @throws CmsXmlException if something goes wrong
630     */
631    @Deprecated
632    I_CmsWidget getWidget(I_CmsXmlSchemaType value) throws CmsXmlException;
633
634    /**
635     * Returns true if the contents for this content handler have schema-based formatters which can be disabled or enabled.<p>
636     *
637     * @return true if the contents for this content handler have schema-based formatters which can be disabled or enabled
638     */
639    boolean hasModifiableFormatters();
640
641    /**
642     * Returns whether there are nested formatters configured for this content type.<p>
643     *
644     * @return <code>true</code> if there are nested formatters configured for this content type
645     */
646    boolean hasNestedFormatters();
647
648    /**
649     * Returns if there are locale synchronized elements configured.<p>
650     *
651     * @return <code>true</code> if there are locale synchronized elements configured
652     */
653    boolean hasSynchronizedElements();
654
655    /**
656     * Returns if there are visibility handlers configured for this content type.<p>
657     *
658     * @return <code>true</code> if there are visibility handlers configured for this content type
659     */
660    boolean hasVisibilityHandlers();
661
662    /**
663     * Initializes this content handler for the given XML content definition by
664     * analyzing the "appinfo" node.<p>
665     *
666     * @param appInfoElement the "appinfo" element root node to analyze
667     * @param contentDefinition the XML content definition that XML content handler belongs to
668     *
669     * @throws CmsXmlException if something goes wrong
670     */
671    void initialize(Element appInfoElement, CmsXmlContentDefinition contentDefinition) throws CmsXmlException;
672
673    /**
674     * Performs a check of the given XML document.<p>
675     *
676     * The main difference to the {@link #resolveValidation(CmsObject, I_CmsXmlContentValue, CmsXmlContentErrorHandler)}
677     * method is that this method may silently remove some values, for instance, for broken links.<p>
678     *
679     * @param cms the current OpenCms user context
680     * @param document the document to resolve the check rules for
681     */
682    void invalidateBrokenLinks(CmsObject cms, CmsXmlContent document);
683
684    /**
685     * Checks whether the Acacia editor is disabled for this type.<p>
686     *
687     * @return true if the Acacia editor is disabled
688     */
689    boolean isAcaciaEditorDisabled();
690
691    /**
692     * Returns <code>true</code> if the XML content should be indexed when it is dropped in a container page,
693     * and returns <code>false</code> if this XML content should be indexed as 'stand-alone' document.<p>
694     *
695     * This flag is intended by excluding XML contents from the search index that are not used as detail pages,
696     * but to index those extraction result when they are part of a container page.<p>
697     *
698     * In order to set this falg add an attribute <code>containerpageOnly="true"</code> to the
699     * <code>'&lt;searchsettings&gt;-node'</code> of the XSD of the resource type you want to be indexed only
700     * when it is part of a container page.<p>
701     *
702     * @return the container page only flag
703     */
704    boolean isContainerPageOnly();
705
706    /**
707     * Returns <code>true</code> in case the given value should be searchable with
708     * the integrated full text search.<p>
709     *
710     * For the full text search, the value of all elements in one locale of the XML content are combined
711     * to one big text, which is referred to as the "content" in the context of the full text search.
712     * With this option, it is possible to hide certain elements from this "content" that does not make sense
713     * to include in the full text search.<p>
714     *
715     * @param value the XML content value to check
716     *
717     * @return <code>true</code> in case the given value should be searchable
718     *
719     * @deprecated use {@link #getSearchContentType(I_CmsXmlContentValue)} instead. Will be removed if plain lucene search is removed.
720     */
721    @Deprecated
722    default boolean isSearchable(I_CmsXmlContentValue value) {
723
724        return Objects.equals(getSearchContentType(value), SearchContentType.TRUE);
725    }
726
727    /**
728     * Returns if the given content field should be visible to the current user.<p>
729     *
730     * @param cms the cms context
731     * @param schemaType the content value type
732     * @param valuePath the value path
733     * @param resource the edited resource
734     * @param contentLocale the content locale
735     *
736     * @return <code>true</code> if the given content field should be visible to the current user
737     */
738    boolean isVisible(
739        CmsObject cms,
740        I_CmsXmlSchemaType schemaType,
741        String valuePath,
742        CmsResource resource,
743        Locale contentLocale);
744
745    /**
746     * Prepares the given XML content to be used after it was read from the OpenCms VFS.<p>
747     *
748     * This method is always called after any content is unmarshalled.
749     * It can be used to perform customized actions on the given XML content.<p>
750     *
751     * @param cms the current OpenCms user context
752     * @param content the XML content to be used as read from the VFS
753     *
754     * @return the prepared content to be used
755     */
756    CmsXmlContent prepareForUse(CmsObject cms, CmsXmlContent content);
757
758    /**
759     * Prepares the given XML content to be written to the OpenCms VFS.<p>
760     *
761     * This method is always called before any content gets written.
762     * It can be used to perform XML validation, pretty - printing
763     * or customized actions on the given XML content.<p>
764     *
765     * @param cms the current OpenCms user context
766     * @param content the XML content to be written
767     * @param file the resource the XML content in it's current state was unmarshalled from
768     *
769     * @return the file to write to the OpenCms VFS, this will be an updated version of the parameter file
770     *
771     * @throws CmsException in case something goes wrong
772     */
773    CmsFile prepareForWrite(CmsObject cms, CmsXmlContent content, CmsFile file) throws CmsException;
774
775    /**
776     * Resolves the value mappings of the given XML content value, according
777     * to the rules of this XML content handler.<p>
778     *
779     * @param cms the current OpenCms user context
780     * @param content the XML content to resolve the mappings for
781     * @param value the value to resolve the mappings for
782     *
783     * @throws CmsException if something goes wrong
784     */
785    void resolveMapping(CmsObject cms, CmsXmlContent content, I_CmsXmlContentValue value) throws CmsException;
786
787    /**
788     * Performs a validation of the given XML content value, and saves all errors or warnings found in
789     * the provided XML content error handler.<p>
790     *
791     * The errorHandler parameter is optional, if <code>null</code> is given a new error handler
792     * instance must be created.<p>
793     *
794     * @param cms the current OpenCms user context
795     * @param value the value to resolve the validation rules for
796     * @param errorHandler (optional) an error handler instance that contains previous error or warnings
797     *
798     * @return an error handler that contains all errors and warnings currently found
799     */
800    CmsXmlContentErrorHandler resolveValidation(
801        CmsObject cms,
802        I_CmsXmlContentValue value,
803        CmsXmlContentErrorHandler errorHandler);
804
805}