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;
029
030import org.opencms.file.CmsFile;
031import org.opencms.file.CmsObject;
032import org.opencms.staticexport.CmsLinkProcessor;
033import org.opencms.staticexport.CmsLinkTable;
034import org.opencms.xml.content.CmsXmlContentErrorHandler;
035import org.opencms.xml.content.I_CmsXmlContentHandler;
036import org.opencms.xml.types.I_CmsXmlContentValue;
037
038import java.util.List;
039import java.util.Locale;
040
041/**
042 * Describes the API to access the values of a XML content document.<p>
043 *
044 * @since 6.0.0
045 */
046public interface I_CmsXmlDocument {
047
048    /**
049     * Adds the given locale to this XML document.<p>
050     *
051     * @param cms the current users OpenCms context
052     * @param locale the locale to add
053     *
054     * @throws CmsXmlException in case the locale already existed, or if something else goes wrong
055     */
056    void addLocale(CmsObject cms, Locale locale) throws CmsXmlException;
057
058    /**
059     * Copies the content from the first matching source locale that exists in this XML document
060     * to the given destination locale in this XML document.<p>
061     *
062     * The list of possible sources, has to be sorted in order of preference.
063     * The first match that exists in this XML document is used as source for the destination locale.
064     * No "locale simplification" ("en_EN" to "en" etc.) is performed for the match.<p>
065     *
066     * @param possibleSources the possible source locales in order of preference,
067     *      must contain objects of type {@link Locale}
068     * @param destination the destination locale
069     *
070     * @throws CmsXmlException in case non of the source locales did not exist,
071     *      or the destination locale already exists in the document, or if something else goes wrong
072     */
073    void copyLocale(List<Locale> possibleSources, Locale destination) throws CmsXmlException;
074
075    /**
076     * Copies the content of the given source locale to the given destination locale in this XML document.<p>
077     *
078     * @param source the source locale
079     * @param destination the destination locale
080     *
081     * @throws CmsXmlException in case either the source locale did not exist,
082     *      or the destination locale already exists in the document, or if something else goes wrong
083     */
084    void copyLocale(Locale source, Locale destination) throws CmsXmlException;
085
086    /**
087     * Returns the first matching locale (eventually simplified) from the available locales.<p>
088     *
089     * In case no match is found, code <code>null</code> is returned.<p>
090     *
091     * @param locale the requested locale
092     *
093     * @return the matching locale available within the document
094     */
095    Locale getBestMatchingLocale(Locale locale);
096
097    /**
098     * Returns the content definition object used for this XML document.<p>
099     *
100     * @return the content definition object used for this XML document
101     */
102    CmsXmlContentDefinition getContentDefinition();
103
104    /**
105     * Returns the content conversion parameter used for this XML document.<p>
106     *
107     * @return the content conversion parameter used for this XML document
108     */
109    String getConversion();
110
111    /**
112     * Returns the encoding used for this XML document.<p>
113     *
114     * @return the encoding used for this XML document
115     */
116    String getEncoding();
117
118    /**
119     * Returns the file this document was generated from, may be <code>null</code> if the file not available.<p>
120     *
121     * The file may not be available if the document was generated from a String or a pure XML document.<p>
122     *
123     * @return the file this document was generated from
124     */
125    CmsFile getFile();
126
127    /**
128     * Returns the content handler associated with the content definition of this XML document.<p>
129     *
130     * This is a shortcut for <code>getContentDefinition().getContentHandler()</code>.<p>
131     *
132     * @return the content handler associated with the content definition of this XML document
133     */
134    I_CmsXmlContentHandler getHandler();
135
136    /**
137     * Returns the index count of existing values for the given path,
138     * or <code>-1</code> if no such path exists.<p>
139     *
140     * @param path the path to get the index count for
141     * @param locale the locale to get the index count for
142     *
143     * @return the index count for the given key name
144     */
145    int getIndexCount(String path, Locale locale);
146
147    /**
148     * Returns a link processor for the values of this XML document.<p>
149     *
150     * @param cms the current OpenCms user context that provides access to the link processor
151     * @param linkTable the table with the links to process
152     *
153     * @return a link processor for the values of this XML document
154     */
155    CmsLinkProcessor getLinkProcessor(CmsObject cms, CmsLinkTable linkTable);
156
157    /**
158     * Returns a List of all locales that have at last one value in this XML document.<p>
159     *
160     * @return a List of all locales that have at last one value in this XML document
161     */
162    List<Locale> getLocales();
163
164    /**
165     * Returns a List of all locales that have at least one element with the given path in this XML document.<p>
166     *
167     * If no locale for the given element name is available, an empty list is returned.<p>
168     *
169     * @param path the path to look up the locale List for
170     * @return a List of all locales that have at least one element with the given path in this XML document
171     */
172    List<Locale> getLocales(String path);
173
174    /**
175     * Returns a List of all available elements paths (Strings) used in this document for the given locale.<p>
176     *
177     * If no element for the given locale is available, an empty list is returned.<p>
178     *
179     * @param locale the locale to look up the elements paths for
180     * @return a List of all available elements paths (Strings) used in this document for the given locale
181     *
182     * @see #getValues(Locale)
183     */
184    List<String> getNames(Locale locale);
185
186    /**
187     * Returns the first content value for the given path as a String,
188     * or <code>null</code> if no such value exists.<p>
189     *
190     * @param cms the current OpenCms user context
191     * @param path the path to get the content value for
192     * @param locale the locale to get the content value for
193     *
194     * @return the first content value for the given path as a String
195     *
196     * @throws CmsXmlException if something goes wrong
197     */
198    String getStringValue(CmsObject cms, String path, Locale locale) throws CmsXmlException;
199
200    /**
201     * Returns the content value for the given path and the selected index as a String,
202     * or <code>null</code> if no such value exists.<p>
203     *
204     * @param cms the current OpenCms user context
205     * @param path the path to get the content value for
206     * @param locale the locale to get the content value for
207     * @param index the index position to get the value from
208     *
209     * @return the content value for the given path and the selected index as a String
210     *
211     * @throws CmsXmlException if something goes wrong
212     */
213    String getStringValue(CmsObject cms, String path, Locale locale, int index) throws CmsXmlException;
214
215    /**
216     * Returns all content values (of type {@link I_CmsXmlContentValue}) directly below the given path
217     * available in this document for the given locale.<p>
218     *
219     * If no content value for the given path is available with this locale, an empty list is returned.<p>
220     *
221     * @param path the path to get the sub content values for
222     * @param locale the locale to get the sub content values for
223     *
224     * @return all content values (of type {@link I_CmsXmlContentValue}) directly below the given path
225     *      available in this document for the given locale
226     */
227    List<I_CmsXmlContentValue> getSubValues(String path, Locale locale);
228
229    /**
230     * Returns the content value Object for the given path,
231     * or <code>null</code> if no such value exists.<p>
232     *
233     * You can provide an index by appending a number in square brackets
234     * to the path parameter like this "Title[1]".
235     * If no index is provided, 1 is used for the index position.<p>
236     *
237     * @param path the path to get the content value for
238     * @param locale the locale to get the content value for
239     *
240     * @return the content value Object for the given path
241     */
242    I_CmsXmlContentValue getValue(String path, Locale locale);
243
244    /**
245     * Returns the content value Object for the given path and the selected index,
246     * or <code>null</code> if no such value exists.<p>
247     *
248     * @param path the path to get the content value for
249     * @param locale the locale to get the content value for
250     * @param index the index position to get the value from
251     *
252     * @return the content value Object for the given path and the selected index
253     */
254    I_CmsXmlContentValue getValue(String path, Locale locale, int index);
255
256    /**
257     * Returns all available content values (of type {@link I_CmsXmlContentValue})
258     * in this document for the given locale.<p>
259     *
260     * If no content value for the given locale is available, an empty list is returned.<p>
261     *
262     * @param locale the locale to get the content values for
263     * @return all available content values (of type {@link I_CmsXmlContentValue}) in this document for the given locale
264     *
265     * @see #getNames(Locale)
266     */
267    List<I_CmsXmlContentValue> getValues(Locale locale);
268
269    /**
270     * Returns all content values (of type {@link I_CmsXmlContentValue}) with the given path
271     * available in this document for the given locale.<p>
272     *
273     * If no content value for the given path is available with this locale, an empty list is returned.<p>
274     *
275     * @param path the path to get the content values for
276     * @param locale the locale to get the content values for
277     *
278     * @return all content values (of type {@link I_CmsXmlContentValue}) with the given path
279     *      available in this document for the given locale
280     */
281    List<I_CmsXmlContentValue> getValues(String path, Locale locale);
282
283    /**
284     * Returns <code>true</code> if the given locale exists in this XML document.<p>
285     *
286     * @param locale the locale to check
287     *
288     * @return <code>true</code> if the given locale exists in this XML document, <code>false</code> otherwise
289     */
290    boolean hasLocale(Locale locale);
291
292    /**
293     * Returns <code>true</code> if a value with the given path exists for the selected locale in this XML document, or
294     * <code>false</code> otherwise.<p>
295     *
296     * You can provide an index by appending a number in square brackets
297     * to the path parameter like this "Title[1]".
298     * If no index is provided, 1 is used for the index position.<p>
299     *
300     * @param path the path to check
301     * @param locale the locale to check
302     *
303     * @return <code>true</code> if a value with the given path exists for the selected locale in this XML document
304     */
305    boolean hasValue(String path, Locale locale);
306
307    /**
308     * Returns <code>true</code> if a value with the given path and the provided index exists for the selected locale
309     * in this XML document, or <code>false</code> otherwise.<p>
310     *
311     * @param path the path to check
312     * @param locale the locale to check
313     * @param index the index position to check
314     *
315     * @return <code>true</code> if a value with the given path and the provided index exists for the selected locale
316     *      in this XML document
317     */
318    boolean hasValue(String path, Locale locale, int index);
319
320    /**
321     * Initializes this XML document, required after structural changes to the internal XML.<p>
322     *
323     * If nodes in the XML are added, removed or moved, the document needs to be initialized in
324     * order to update the internal data structures.<p>
325     */
326    void initDocument();
327
328    /**
329     * Returns <code>true</code> if a value with the given path exists for the selected locale in this XML document,
330     * and that value is enabled,
331     * or <code>false</code> otherwise.<p>
332     *
333     * This is only used with implementations that support enabling and disabling individual values,
334     * such as {@link org.opencms.xml.page.CmsXmlPage}. If enabling / disabling values is not supported,
335     * this is identical to {@link #hasValue(String, Locale)}.<p>
336     *
337     * You can provide an index by appending a number in square brackets
338     * to the path parameter like this "Title[1]".
339     * If no index is provided, 1 is used for the index position.<p>
340     *
341     * @param path the path to check
342     * @param locale the locale to check
343     *
344     * @return <code>true</code> if a value with the given path exists for the selected locale in this XML document,
345     *      and that value is enabled
346     */
347    boolean isEnabled(String path, Locale locale);
348
349    /**
350     * Returns <code>true</code> if a value with the given path and the provided index exists for the selected locale
351     * in this XML document, and that value is enabled, or <code>false</code> otherwise.<p>
352     *
353     * This is only used with implementations that support enabling and disabling individual values,
354     * such as {@link org.opencms.xml.page.CmsXmlPage}. If enabling / disabling values is not supported,
355     * this is identical to {@link #hasValue(String, Locale, int)}.<p>
356     *
357     * @param path the path to check
358     * @param locale the locale to check
359     * @param index the index position to check
360     *
361     * @return <code>true</code> if a value with the given path and the provided index exists for the selected locale
362     *      in this XML document, and that value is enabled
363     */
364    boolean isEnabled(String path, Locale locale, int index);
365
366    /**
367     * Moves the content of the given source locale to the given destination locale in this XML document.<p>
368     *
369     * @param source the source locale
370     * @param destination the destination locale
371     *
372     * @throws CmsXmlException in case either the source locale does not exist,
373     *      or the destination locale already exists in the document, or if something else goes wrong
374     */
375    void moveLocale(Locale source, Locale destination) throws CmsXmlException;
376
377    /**
378     * Removes the given locale from this XML document.
379     *
380     * @param locale the locale to remove
381     *
382     * @throws CmsXmlException in case the locale did not exist in the document, or if something else goes wrong
383     */
384    void removeLocale(Locale locale) throws CmsXmlException;
385
386    /**
387     * Validates the content of this XML document.<p>
388     *
389     * To check for errors in a single document locale only, use
390     * {@link CmsXmlContentErrorHandler#hasErrors(Locale)} in the result object.<p>
391     *
392     * @param cms the current OpenCms user context
393     *
394     * @return an error handler instance that provides information about the errors or warnings that have been found
395     */
396    CmsXmlContentErrorHandler validate(CmsObject cms);
397}