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.types;
029
030import org.opencms.file.CmsObject;
031import org.opencms.xml.I_CmsXmlDocument;
032
033import java.util.Locale;
034
035import org.dom4j.Element;
036
037/**
038 * Provides access to the value of a specific XML content node.<p>
039 *
040 * @since 6.0.0
041 */
042public interface I_CmsXmlContentValue extends I_CmsXmlSchemaType {
043
044    /**
045     * Search content configuration for the value.
046     * The configuration determines how the conent's value should be added to the indexed content fields.
047     */
048    public static class CmsSearchContentConfig {
049
050        /** Configuration for not adding the value to the content fields. */
051        public static final CmsSearchContentConfig FALSE = new CmsSearchContentConfig(SearchContentType.FALSE, null);
052        /** Configuration for adding the extraction of the content linked by the value to the content fields. */
053        public static final CmsSearchContentConfig CONTENT = new CmsSearchContentConfig(
054            SearchContentType.CONTENT,
055            null);
056        /** Configuration for adding the value unchanged to the content fields. */
057        public static final CmsSearchContentConfig TRUE = new CmsSearchContentConfig(SearchContentType.TRUE, null);
058        /** The search content type. */
059        private SearchContentType m_type;
060        /** The adjustment implementation for the value. */
061        private String m_adjustmentClass;
062
063        /**
064         * Constructs a new search content configuration.
065         * @param type the search content type
066         * @param adjustmentClass the adjustment implementation
067         */
068        private CmsSearchContentConfig(SearchContentType type, String adjustmentClass) {
069
070            m_type = type;
071            m_adjustmentClass = adjustmentClass;
072        }
073
074        /**
075         * Returns the configuration for the search content type.
076         * @param searchContentType the type to get the configuration for
077         * @return the configuration for the type
078         */
079        public static CmsSearchContentConfig get(SearchContentType searchContentType) {
080
081            return get(searchContentType, null);
082        }
083
084        /**
085         * Returns the configuration for the combination of search content type and adjustment class.
086         * @param searchContentType the type to get the configuration for
087         * @param adjustmentClass the adjustment class
088         * @return the configuration for the type/adjustment combination.
089         */
090        public static CmsSearchContentConfig get(SearchContentType searchContentType, String adjustmentClass) {
091
092            if (searchContentType == null) {
093                return adjustmentClass == null
094                ? null
095                : new CmsSearchContentConfig(SearchContentType.TRUE, adjustmentClass);
096            }
097            switch (searchContentType) {
098                case FALSE:
099                    return FALSE;
100                case TRUE:
101                    return adjustmentClass == null
102                    ? TRUE
103                    : new CmsSearchContentConfig(SearchContentType.TRUE, adjustmentClass);
104                case CONTENT:
105                    return CONTENT;
106                default:
107                    return null;
108            }
109        }
110
111        /**
112         * @return the adjustment class.
113         */
114        public String getAdjustmentClass() {
115
116            return m_adjustmentClass;
117        }
118
119        /**
120         * @return the search content type.
121         */
122        public SearchContentType getSearchContentType() {
123
124            return m_type;
125        }
126    }
127
128    /**
129     * The available search types for element searchsetting.
130     */
131    public static enum SearchContentType {
132
133        /** Do not merge the value of the field into the content field. */
134        FALSE,
135        /** Merge the value of the field into the content field. */
136        TRUE,
137        /** Merge the extracted content of the resource linked by the element into the content field. */
138        CONTENT;
139
140        /**
141         * Converts the String into a SearchContentType. Returns <code>null</code> if conversion is not possible.
142         * @param type the search content type as String.
143         * @return the search content type specified by the provided String, or <code>null</code> if the String did not specify any search content type.
144         */
145        public static SearchContentType fromString(String type) {
146
147            if (null == type) {
148                return null;
149            }
150            switch (type.toLowerCase()) {
151                case "false":
152                    return FALSE;
153                case "true":
154                    return TRUE;
155                case "content":
156                    return CONTENT;
157                default:
158                    return null;
159            }
160        }
161
162    }
163
164    /**
165     * Returns the XML content instance this value belongs to.<p>
166     *
167     * @return the XML content instance this value belongs to
168     */
169    I_CmsXmlDocument getDocument();
170
171    /**
172     * Returns the original XML element of this XML content value.<p>
173     *
174     * @return the original XML element of this XML content value
175     */
176    Element getElement();
177
178    /**
179     * Returns the node index of this XML content value in the source XML document,
180     * starting with 0, with special handling of elements in choice groups.<p>
181     *
182     * This is useful in case there are more than one elements
183     * with the same XML node name in the source XML document.<p>
184     *
185     * Elements in XML choice groups will share the same number space, so a choice
186     * sequence will be numbered like this:
187     * <code>Title[1], Text[2], Title[3], Image[4]</code><p>
188     *
189     * @return the index of this XML content node in the source document with special handling of elements in choice groups
190     *
191     * @see #getXmlIndex()
192     */
193    int getIndex();
194
195    /**
196     * Returns the locale of this XML content value was generated for.<p>
197     *
198     * @return the locale of this XML content value was generated for
199     */
200    Locale getLocale();
201
202    /**
203     * Returns the total number of XML elements of this type that currently exist in the source document.<p>
204     *
205     * @return the total number of XML elements of this type that currently exist in the source document
206     */
207    int getMaxIndex();
208
209    /**
210     * Returns the path of this XML content value in the source document.<p>
211     *
212     * @return the path of this XML content value in the source document
213     */
214    String getPath();
215
216    /**
217     * Returns the value of this XML content node as a plain text String.<p>
218     *
219     * Plain text in this context means a pure textual representation
220     * of the content (i.e. without html tags).
221     * The plain text may be <code>null</code>, too, if there is no sound or useful
222     * textual representation (i.e. color values).<p>
223     *
224     * @param cms an initialized instance of a CmsObject
225     *
226     * @return the value of this XML content node as a plain text String
227     */
228    String getPlainText(CmsObject cms);
229
230    /**
231     * Returns the search content type for the value. Default implementation uses the historic isSearchable() method.
232     * @return the search content type
233     */
234    default CmsSearchContentConfig getSearchContentConfig() {
235
236        return new CmsSearchContentConfig(isSearchable() ? SearchContentType.TRUE : SearchContentType.FALSE, null);
237    }
238
239    /**
240     * Returns the value of this XML content node as a String.<p>
241     *
242     * @param cms an initialized instance of a CmsObject
243     *
244     * @return the value of this XML content node as a String
245     */
246    String getStringValue(CmsObject cms);
247
248    /**
249     * Returns the node index of this XML content value in the source XML document,
250     * starting with 0, based on the XML ordering.<p>
251     *
252     * Elements in choice groups will be numbered like this:
253     * <code>Title[1], Text[1], Title[2], Image[1]</code><p>
254     *
255     * @return the index of this XML content node in the source document with special handling of elements in choice groups
256     *
257     * @see #getIndex()
258     */
259    int getXmlIndex();
260
261    /**
262     * Returns <code>true</code> in case this value is searchable by default with
263     * the integrated full text search.<p>
264     *
265     * @return <code>true</code> in case this value is searchable by default
266     */
267    boolean isSearchable();
268
269    /**
270     * Moves this XML content value one position down in the source document, if possible.<p>
271     *
272     * If the XML content value is already the first in it's sequence, it is not moved.<p>
273     */
274    void moveDown();
275
276    /**
277     * Moves this XML content value one position up in the source document, if possible.<p>
278     *
279     * If the XML content value is already the last in it's sequence, it is not moved.<p>
280     */
281    void moveUp();
282
283    /**
284     * Sets the provided String as value of this XML content node.<p>
285     *
286     * This method does provide processing of the content based on the
287     * users current OpenCms context. This can be used e.g. for link
288     * extraction and replacement in the content.<p>
289     *
290     * @param cms an initialized instance of a CmsObject
291     * @param value the value to set
292     *
293     */
294    void setStringValue(CmsObject cms, String value);
295}