001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://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, please see the
018 * company website: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://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.ade.configuration.CmsADEConfigData;
031import org.opencms.file.CmsObject;
032
033import java.util.Locale;
034
035/**
036 * Interface for 'content augmentations' which can be used to augment the currently edited content.
037 *
038 * <p>This can effectively replace the complete content, but in
039 */
040public interface I_CmsXmlContentAugmentation {
041
042    /**
043     * Context provided to the content augmentation class.
044     *
045     * <p>Used to access the original content, the currently edited locale, the current CmsObject, etc., and to send the new content back to the editor at the end.
046     */
047    public interface Context {
048
049        public String getParameter(String param);
050
051        /**
052         * Helper method for calling the JSP at the given path.
053         *
054         * <p>The context will be made available as the request attribute 'context' in the called JSP.
055         *
056         * <p>This method can not be used reentrantly (i.e. from a JSP which has already been called via callJsp).
057         *
058         * @param path the path of the JSP to call
059         * @throws Exception if something goes wrong
060         */
061        void callJsp(String path) throws Exception;
062
063        /**
064         * The ADE configuration that's currently being used.
065         *
066         * @return the ADE configuration
067         */
068        CmsADEConfigData getADEConfig();
069
070        /**
071         * Gets the current CMS context.
072         *
073         * @return the current CMS context
074         */
075        CmsObject getCmsObject();
076
077        /**
078         * Gets a copy of the currently edited XML content.
079         *
080         * <p>Modifying this object by itself does not do anything for the content editor, you have to send either the modified object
081         * or another modified copy back to the content editor via setResult().
082         *
083         * @return a copy of the currently edited XML content
084         */
085        CmsXmlContent getContent();
086
087        /**
088         * Gets the currently edited locale of the content.
089         *
090         * @return the currently edited locale of the content
091         */
092        Locale getLocale();
093
094        boolean isAborted();
095
096        void progress(String progressMessage);
097
098        /**
099         * Sets the HTML to display to the user after the augmentation.
100         * @param message
101         */
102        void setHtmlMessage(String message);
103
104        /**
105         * Sets the locale to switch to.
106         *
107         * <p>If not called, the current locale will be used if possible.
108         *
109         * @param locale the locale to switch to
110         */
111        void setNextLocale(Locale locale);
112
113        /**
114         * Sends the augmented content back to the content editor.
115         * @param result the augmented content
116         */
117        void setResult(CmsXmlContent result);
118    }
119
120    /**
121     * The name of the request attribute used to pass the augmentation context to JSPs.
122     */
123    public static final String ATTR_CONTEXT = "context";
124
125    /**
126     * Augments the content provided in the given context.
127     *
128     *  <p>Implementations can query the given context for information like the original XML content and the current locale, do some processing,
129     *  and, in the end, call the setResult method to provide the finished, augmented content.
130     *
131     * @param context the augmentation context - provides access to the content and further information
132     * @throws Exception if something goes wrong
133     */
134    void augmentContent(Context context) throws Exception;
135
136}