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     * The available search types for element searchsetting.
046     */
047    public static enum SearchContentType {
048        /** Do not merge the value of the field into the content field. */
049        FALSE,
050        /** Merge the value of the field into the content field. */
051        TRUE,
052        /** Merge the extracted content of the resource linked by the element into the content field. */
053        CONTENT;
054
055        /**
056         * Converts the String into a SearchContentType. Returns <code>null</code> if conversion is not possible.
057         * @param type the search content type as String.
058         * @return the search content type specified by the provided String, or <code>null</code> if the String did not specify any search content type.
059         */
060        public static SearchContentType fromString(String type) {
061
062            if (null == type) {
063                return null;
064            }
065            switch (type.toLowerCase()) {
066                case "false":
067                    return FALSE;
068                case "true":
069                    return TRUE;
070                case "content":
071                    return CONTENT;
072                default:
073                    return null;
074            }
075        }
076    }
077
078    /**
079     * Returns the XML content instance this value belongs to.<p>
080     *
081     * @return the XML content instance this value belongs to
082     */
083    I_CmsXmlDocument getDocument();
084
085    /**
086     * Returns the original XML element of this XML content value.<p>
087     *
088     * @return the original XML element of this XML content value
089     */
090    Element getElement();
091
092    /**
093     * Returns the node index of this XML content value in the source XML document,
094     * starting with 0, with special handling of elements in choice groups.<p>
095     *
096     * This is useful in case there are more than one elements
097     * with the same XML node name in the source XML document.<p>
098     *
099     * Elements in XML choice groups will share the same number space, so a choice
100     * sequence will be numbered like this:
101     * <code>Title[1], Text[2], Title[3], Image[4]</code><p>
102     *
103     * @return the index of this XML content node in the source document with special handling of elements in choice groups
104     *
105     * @see #getXmlIndex()
106     */
107    int getIndex();
108
109    /**
110     * Returns the locale of this XML content value was generated for.<p>
111     *
112     * @return the locale of this XML content value was generated for
113     */
114    Locale getLocale();
115
116    /**
117     * Returns the total number of XML elements of this type that currently exist in the source document.<p>
118     *
119     * @return the total number of XML elements of this type that currently exist in the source document
120     */
121    int getMaxIndex();
122
123    /**
124     * Returns the path of this XML content value in the source document.<p>
125     *
126     * @return the path of this XML content value in the source document
127     */
128    String getPath();
129
130    /**
131     * Returns the value of this XML content node as a plain text String.<p>
132     *
133     * Plain text in this context means a pure textual representation
134     * of the content (i.e. without html tags).
135     * The plain text may be <code>null</code>, too, if there is no sound or useful
136     * textual representation (i.e. color values).<p>
137     *
138     * @param cms an initialized instance of a CmsObject
139     *
140     * @return the value of this XML content node as a plain text String
141     */
142    String getPlainText(CmsObject cms);
143
144    /**
145     * Returns the search content type for the value. Default implementation uses the historic isSearchable() method.
146     * @return the search content type
147     */
148    default SearchContentType getSearchContentType() {
149
150        return isSearchable() ? SearchContentType.TRUE : SearchContentType.FALSE;
151    }
152
153    /**
154     * Returns the value of this XML content node as a String.<p>
155     *
156     * @param cms an initialized instance of a CmsObject
157     *
158     * @return the value of this XML content node as a String
159     */
160    String getStringValue(CmsObject cms);
161
162    /**
163     * Returns the node index of this XML content value in the source XML document,
164     * starting with 0, based on the XML ordering.<p>
165     *
166     * Elements in choice groups will be numbered like this:
167     * <code>Title[1], Text[1], Title[2], Image[1]</code><p>
168     *
169     * @return the index of this XML content node in the source document with special handling of elements in choice groups
170     *
171     * @see #getIndex()
172     */
173    int getXmlIndex();
174
175    /**
176     * Returns <code>true</code> in case this value is searchable by default with
177     * the integrated full text search.<p>
178     *
179     * @return <code>true</code> in case this value is searchable by default
180     */
181    boolean isSearchable();
182
183    /**
184     * Moves this XML content value one position down in the source document, if possible.<p>
185     *
186     * If the XML content value is already the first in it's sequence, it is not moved.<p>
187     */
188    void moveDown();
189
190    /**
191     * Moves this XML content value one position up in the source document, if possible.<p>
192     *
193     * If the XML content value is already the last in it's sequence, it is not moved.<p>
194     */
195    void moveUp();
196
197    /**
198     * Sets the provided String as value of this XML content node.<p>
199     *
200     * This method does provide processing of the content based on the
201     * users current OpenCms context. This can be used e.g. for link
202     * extraction and replacement in the content.<p>
203     *
204     * @param cms an initialized instance of a CmsObject
205     * @param value the value to set
206     *
207     */
208    void setStringValue(CmsObject cms, String value);
209}