001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/xml/I_CmsXmlDocument.java,v $
003: * Date : $Date: 2008-02-27 12:05:50 $
004: * Version: $Revision: 1.21 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software GmbH, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.xml;
033:
034: import org.opencms.file.CmsFile;
035: import org.opencms.file.CmsObject;
036: import org.opencms.staticexport.CmsLinkProcessor;
037: import org.opencms.staticexport.CmsLinkTable;
038: import org.opencms.xml.content.CmsXmlContentErrorHandler;
039: import org.opencms.xml.types.I_CmsXmlContentValue;
040:
041: import java.util.List;
042: import java.util.Locale;
043:
044: /**
045: * Describes the API to access the values of a XML content document.<p>
046: *
047: * @author Alexander Kandzior
048: *
049: * @version $Revision: 1.21 $
050: *
051: * @since 6.0.0
052: */
053: public interface I_CmsXmlDocument {
054:
055: /**
056: * Adds the given locale to this XML document.<p>
057: *
058: * @param cms the current users OpenCms context
059: * @param locale the locale to add
060: *
061: * @throws CmsXmlException in case the locale already existed, or if something else goes wrong
062: */
063: void addLocale(CmsObject cms, Locale locale) throws CmsXmlException;
064:
065: /**
066: * Copies the content from the first matching source locale that exists in this XML document
067: * to the given destination locale in this XML document.<p>
068: *
069: * The list of possible sources, has to be sorted in order of preference.
070: * The first match that exists in this XML document is used as source for the destination locale.
071: * No "locale simplification" ("en_EN" to "en" etc.) is performed for the match.<p>
072: *
073: * @param possibleSources the possible source locales in order of preference,
074: * must contain objects of type {@link Locale}
075: * @param destination the destination locale
076: *
077: * @throws CmsXmlException in case non of the source locales did not exist,
078: * or the destination locale already exists in the document, or if something else goes wrong
079: */
080: void copyLocale(List possibleSources, Locale destination)
081: throws CmsXmlException;
082:
083: /**
084: * Copies the content of the given source locale to the given destination locale in this XML document.<p>
085: *
086: * @param source the source locale
087: * @param destination the destination locale
088: *
089: * @throws CmsXmlException in case either the source locale did not exist,
090: * or the destination locale already exists in the document, or if something else goes wrong
091: */
092: void copyLocale(Locale source, Locale destination)
093: throws CmsXmlException;
094:
095: /**
096: * Returns the content definition object used for this XML document.<p>
097: *
098: * @return the content definition object used for this XML document
099: */
100: CmsXmlContentDefinition getContentDefinition();
101:
102: /**
103: * Returns the content conversion parameter used for this XML document.<p>
104: *
105: * @return the content conversion parameter used for this XML document
106: */
107: String getConversion();
108:
109: /**
110: * Returns the encoding used for this XML document.<p>
111: *
112: * @return the encoding used for this XML document
113: */
114: String getEncoding();
115:
116: /**
117: * Returns the file this document was generated from, may be <code>null</code> if the file not available.<p>
118: *
119: * The file may not be available if the document was generated from a String or a pure XML document.<p>
120: *
121: * @return the file this document was generated from
122: */
123: CmsFile getFile();
124:
125: /**
126: * Returns the index count of existing values for the given path,
127: * or <code>-1</code> if no such path exists.<p>
128: *
129: * @param path the path to get the index count for
130: * @param locale the locale to get the index count for
131: *
132: * @return the index count for the given key name
133: */
134: int getIndexCount(String path, Locale locale);
135:
136: /**
137: * Returns a link processor for the values of this XML document.<p>
138: *
139: * @param cms the current OpenCms user context that provides access to the link processor
140: * @param linkTable the table with the links to process
141: *
142: * @return a link processor for the values of this XML document
143: */
144: CmsLinkProcessor getLinkProcessor(CmsObject cms,
145: CmsLinkTable linkTable);
146:
147: /**
148: * Returns a List of all locales that have at last one value in this XML document.<p>
149: *
150: * @return a List of all locales that have at last one value in this XML document
151: */
152: List getLocales();
153:
154: /**
155: * Returns a List of all locales that have at least one element with the given path in this XML document.<p>
156: *
157: * If no locale for the given element name is available, an empty list is returned.<p>
158: *
159: * @param path the path to look up the locale List for
160: * @return a List of all locales that have at least one element with the given path in this XML document
161: */
162: List getLocales(String path);
163:
164: /**
165: * Returns a List of all available elements paths (Strings) used in this document for the given locale.<p>
166: *
167: * If no element for the given locale is available, an empty list is returned.<p>
168: *
169: * @param locale the locale to look up the elements paths for
170: * @return a List of all available elements paths (Strings) used in this document for the given locale
171: *
172: * @see #getValues(Locale)
173: */
174: List getNames(Locale locale);
175:
176: /**
177: * Returns the first content value for the given path as a String,
178: * or <code>null</code> if no such value exists.<p>
179: *
180: * @param cms the current OpenCms user context
181: * @param path the path to get the content value for
182: * @param locale the locale to get the content value for
183: *
184: * @return the first content value for the given path as a String
185: *
186: * @throws CmsXmlException if something goes wrong
187: */
188: String getStringValue(CmsObject cms, String path, Locale locale)
189: throws CmsXmlException;
190:
191: /**
192: * Returns the content value for the given path and the selected index as a String,
193: * or <code>null</code> if no such value exists.<p>
194: *
195: * @param cms the current OpenCms user context
196: * @param path the path to get the content value for
197: * @param locale the locale to get the content value for
198: * @param index the index position to get the value from
199: *
200: * @return the content value for the given path and the selected index as a String
201: *
202: * @throws CmsXmlException if something goes wrong
203: */
204: String getStringValue(CmsObject cms, String path, Locale locale,
205: int index) throws CmsXmlException;
206:
207: /**
208: * Returns the content value Object for the given path,
209: * or <code>null</code> if no such value exists.<p>
210: *
211: * You can provide an index by appending a number in square brackets
212: * to the path parameter like this "Title[1]".
213: * If no index is provided, 1 is used for the index position.<p>
214: *
215: * @param path the path to get the content value for
216: * @param locale the locale to get the content value for
217: *
218: * @return the content value Object for the given path
219: */
220: I_CmsXmlContentValue getValue(String path, Locale locale);
221:
222: /**
223: * Returns the content value Object for the given path and the selected index,
224: * or <code>null</code> if no such value exists.<p>
225: *
226: * @param path the path to get the content value for
227: * @param locale the locale to get the content value for
228: * @param index the index position to get the value from
229: *
230: * @return the content value Object for the given path and the selected index
231: */
232: I_CmsXmlContentValue getValue(String path, Locale locale, int index);
233:
234: /**
235: * Returns all available content values (of type {@link I_CmsXmlContentValue})
236: * in this document for the given locale.<p>
237: *
238: * If no content value for the given locale is available, an empty list is returned.<p>
239: *
240: * @param locale the locale to get the content values for
241: * @return all available content values (of type {@link I_CmsXmlContentValue}) in this document for the given locale
242: *
243: * @see #getNames(Locale)
244: */
245: List getValues(Locale locale);
246:
247: /**
248: * Returns all content values (of type {@link I_CmsXmlContentValue}) with the given path
249: * available in this document for the given locale.<p>
250: *
251: * If no content value for the given path is available with this locale, an empty list is returned.<p>
252: *
253: * @param path the path to get the content values for
254: * @param locale the locale to get the content values for
255: *
256: * @return all content values (of type {@link I_CmsXmlContentValue}) with the given path
257: * available in this document for the given locale
258: */
259: List getValues(String path, Locale locale);
260:
261: /**
262: * Returns <code>true</code> if the given locale exists in this XML document.<p>
263: *
264: * @param locale the locale to check
265: *
266: * @return <code>true</code> if the given locale exists in this XML document, <code>false</code> otherwise
267: */
268: boolean hasLocale(Locale locale);
269:
270: /**
271: * Returns <code>true</code> if a value with the given path exists for the selected locale in this XML document, or
272: * <code>false</code> otherwise.<p>
273: *
274: * You can provide an index by appending a number in square brackets
275: * to the path parameter like this "Title[1]".
276: * If no index is provided, 1 is used for the index position.<p>
277: *
278: * @param path the path to check
279: * @param locale the locale to check
280: *
281: * @return <code>true</code> if a value with the given path exists for the selected locale in this XML document
282: */
283: boolean hasValue(String path, Locale locale);
284:
285: /**
286: * Returns <code>true</code> if a value with the given path and the provided index exists for the selected locale
287: * in this XML document, or <code>false</code> otherwise.<p>
288: *
289: * @param path the path to check
290: * @param locale the locale to check
291: * @param index the index position to check
292: *
293: * @return <code>true</code> if a value with the given path and the provided index exists for the selected locale
294: * in this XML document
295: */
296: boolean hasValue(String path, Locale locale, int index);
297:
298: /**
299: * Initializes this XML document, required after structural changes to the internal XML.<p>
300: *
301: * If nodes in the XML are added, removed or moved, the document needs to be initialized in
302: * order to update the internal data structures.<p>
303: */
304: void initDocument();
305:
306: /**
307: * Returns <code>true</code> if a value with the given path exists for the selected locale in this XML document,
308: * and that value is enabled,
309: * or <code>false</code> otherwise.<p>
310: *
311: * This is only used with implementations that support enabling and disabling individual values,
312: * such as {@link org.opencms.xml.page.CmsXmlPage}. If enabling / disabling values is not supported,
313: * this is identical to {@link #hasValue(String, Locale)}.<p>
314: *
315: * You can provide an index by appending a number in square brackets
316: * to the path parameter like this "Title[1]".
317: * If no index is provided, 1 is used for the index position.<p>
318: *
319: * @param path the path to check
320: * @param locale the locale to check
321: *
322: * @return <code>true</code> if a value with the given path exists for the selected locale in this XML document,
323: * and that value is enabled
324: */
325: boolean isEnabled(String path, Locale locale);
326:
327: /**
328: * Returns <code>true</code> if a value with the given path and the provided index exists for the selected locale
329: * in this XML document, and that value is enabled, or <code>false</code> otherwise.<p>
330: *
331: * This is only used with implementations that support enabling and disabling individual values,
332: * such as {@link org.opencms.xml.page.CmsXmlPage}. If enabling / disabling values is not supported,
333: * this is identical to {@link #hasValue(String, Locale, int)}.<p>
334: *
335: * @param path the path to check
336: * @param locale the locale to check
337: * @param index the index position to check
338: *
339: * @return <code>true</code> if a value with the given path and the provided index exists for the selected locale
340: * in this XML document, and that value is enabled
341: */
342: boolean isEnabled(String path, Locale locale, int index);
343:
344: /**
345: * Moves the content of the given source locale to the given destination locale in this XML document.<p>
346: *
347: * @param source the source locale
348: * @param destination the destination locale
349: *
350: * @throws CmsXmlException in case either the source locale does not exist,
351: * or the destination locale already exists in the document, or if something else goes wrong
352: */
353: void moveLocale(Locale source, Locale destination)
354: throws CmsXmlException;
355:
356: /**
357: * Removes the given locale from this XML document.
358: *
359: * @param locale the locale to remove
360: *
361: * @throws CmsXmlException in case the locale did not exist in the document, or if something else goes wrong
362: */
363: void removeLocale(Locale locale) throws CmsXmlException;
364:
365: /**
366: * Validates the content of this XML document.<p>
367: *
368: * To check for errors in a single document locale only, use
369: * {@link CmsXmlContentErrorHandler#hasErrors(Locale)} in the result object.<p>
370: *
371: * @param cms the current OpenCms user context
372: *
373: * @return an error handler instance that provides information about the errors or warnings that have been found
374: */
375: CmsXmlContentErrorHandler validate(CmsObject cms);
376: }
|