KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > opencms > xml > I_CmsXmlDocument


1 /*
2  * File : $Source: /usr/local/cvs/opencms/src/org/opencms/xml/I_CmsXmlDocument.java,v $
3  * Date : $Date: 2006/03/27 14:52:20 $
4  * Version: $Revision: 1.16 $
5  *
6  * This library is part of OpenCms -
7  * the Open Source Content Mananagement System
8  *
9  * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10  *
11  * This library is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU Lesser General Public
13  * License as published by the Free Software Foundation; either
14  * version 2.1 of the License, or (at your option) any later version.
15  *
16  * This library is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19  * Lesser General Public License for more details.
20  *
21  * For further information about Alkacon Software GmbH, please see the
22  * company website: http://www.alkacon.com
23  *
24  * For further information about OpenCms, please see the
25  * project website: http://www.opencms.org
26  *
27  * You should have received a copy of the GNU Lesser General Public
28  * License along with this library; if not, write to the Free Software
29  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30  */

31
32 package org.opencms.xml;
33
34 import org.opencms.file.CmsFile;
35 import org.opencms.file.CmsObject;
36 import org.opencms.staticexport.CmsLinkProcessor;
37 import org.opencms.staticexport.CmsLinkTable;
38 import org.opencms.xml.content.CmsXmlContentErrorHandler;
39 import org.opencms.xml.types.I_CmsXmlContentValue;
40
41 import java.util.List JavaDoc;
42 import java.util.Locale JavaDoc;
43
44 /**
45  * Describes the API to access the values of a XML content document.<p>
46  *
47  * @author Alexander Kandzior
48  *
49  * @version $Revision: 1.16 $
50  *
51  * @since 6.0.0
52  */

53 public interface I_CmsXmlDocument {
54
55     /**
56      * Adds the given locale to this XML document.
57      *
58      * @param cms the current users OpenCms context
59      * @param locale the locale to add
60      *
61      * @throws CmsXmlException in case the locale already existed, or if something else goes wrong
62      */

63     void addLocale(CmsObject cms, Locale JavaDoc locale) throws CmsXmlException;
64
65     /**
66      * Copies the content of the given source locale to the given destination locale in this XML document.<p>
67      *
68      * @param source the source locale
69      * @param destination the destination locale
70      *
71      * @throws CmsXmlException in case either the source locale did not exist, or the destination locale already exists in the document, or if something else goes wrong
72      */

73     void copyLocale(Locale JavaDoc source, Locale JavaDoc destination) throws CmsXmlException;
74
75     /**
76      * Returns the content definition object for this xml content object.<p>
77      *
78      * @return the content definition object for this xml content object
79      */

80     CmsXmlContentDefinition getContentDefinition();
81
82     /**
83      * Returns the content conversion parameter used for this XML document.<p>
84      *
85      * @return the content conversion parameter used for this XML document
86      */

87     String JavaDoc getConversion();
88
89     /**
90      * Returns the encoding used for this XML document.<p>
91      *
92      * @return the encoding used for this XML document
93      */

94     String JavaDoc getEncoding();
95
96     /**
97      * Returns the file this document was generated from, may be <code>null</code> if the file not available.<p>
98      *
99      * The file may not be available if the document was generated by a String or a pure XML document.<p>
100      *
101      * @return the file this document was generated from
102      */

103     CmsFile getFile();
104
105     /**
106      * Returns the index count of existing values for the given key name,
107      * or <code>-1</code> if no such value exists.<p>
108      *
109      * @param name the key to get the index count for
110      * @param locale the locale to get the index count for
111      *
112      * @return the index count for the given key name
113      */

114     int getIndexCount(String JavaDoc name, Locale JavaDoc locale);
115
116     /**
117      * Returns a link processor for the values of this XML document.<p>
118      *
119      * @param cms the current OpenCms user context that provides access to the link processor
120      * @param linkTable the table with the links to process
121      *
122      * @return a link processor for the values of this XML document
123      */

124     CmsLinkProcessor getLinkProcessor(CmsObject cms, CmsLinkTable linkTable);
125
126     /**
127      * Returns a List of all locales that have at last one element in
128      * this XML document.<p>
129      *
130      * @return a List of all locales that have at last one element in this XML document
131      */

132     List JavaDoc getLocales();
133
134     /**
135      * Returns a List of all locales that have the given element set in this XML document.<p>
136      *
137      * If no locale for the given element name is available, an empty list is returned.<p>
138      *
139      * @param element the element to look up the locale List for
140      * @return a List of all Locales that have the given element set in this XML document
141      */

142     List JavaDoc getLocales(String JavaDoc element);
143
144     /**
145      * Returns all available elements names used in this document for the given locale.<p>
146      *
147      * If no element for the given locale is available, an empty list is returned.<p>
148      *
149      * @param locale the locale
150      * @return list of available element names (Strings)
151      *
152      * @see #getValues(Locale)
153      */

154     List JavaDoc getNames(Locale JavaDoc locale);
155
156     /**
157      * Returns the first content value for the given key name as a String,
158      * or <code>null</code> if no such value exists.<p>.<p>
159      *
160      * @param cms the current OpenCms user context
161      * @param name the key to get the content value for
162      * @param locale the locale to get the content value for
163      *
164      * @return the content value for the given key name
165      *
166      * @throws CmsXmlException if something goes wrong
167      */

168     String JavaDoc getStringValue(CmsObject cms, String JavaDoc name, Locale JavaDoc locale) throws CmsXmlException;
169
170     /**
171      * Returns the content value for the given key name from the selected index as a String,
172      * or <code>null</code> if no such value exists.<p>
173      *
174      * @param cms the current OpenCms user context
175      * @param name the key to get the content value for
176      * @param locale the locale to get the content value for
177      * @param index the index position to get the value from
178      *
179      * @return the content value for the given key name
180      *
181      * @throws CmsXmlException if something goes wrong
182      */

183     String JavaDoc getStringValue(CmsObject cms, String JavaDoc name, Locale JavaDoc locale, int index) throws CmsXmlException;
184
185     /**
186      * Returns the content value Object for the given key name,
187      * or <code>null</code> if no such value exists.<p>.<p>
188      *
189      * You can provide an index for the value by appending a numer in aquare brackets
190      * to the name parameter like this "Title[1]".
191      * If no index is provided, 0 is used for the index position.<p>
192      *
193      * @param name the key to get the content value for
194      * @param locale the locale to get the content value for
195      *
196      * @return the content value for the given key name
197      */

198     I_CmsXmlContentValue getValue(String JavaDoc name, Locale JavaDoc locale);
199
200     /**
201      * Returns the content value Object for the given key name from
202      * the selected index, or <code>null</code> if no such value exists.<p>
203      *
204      * @param name the key to get the content value for
205      * @param locale the locale to get the content value for
206      * @param index the index position to get the value from
207      *
208      * @return the content value for the given key name
209      */

210     I_CmsXmlContentValue getValue(String JavaDoc name, Locale JavaDoc locale, int index);
211
212     /**
213      * Returns all available elements values used in this document for the given locale.<p>
214      *
215      * If no element for the given locale is available, an empty list is returned.<p>
216      *
217      * @param locale the locale
218      * @return list of available element valies (type {@link I_CmsXmlContentValue})
219      *
220      * @see #getNames(Locale)
221      */

222     List JavaDoc getValues(Locale JavaDoc locale);
223
224     /**
225      * Returns all content value Objects for the given key name in a List,
226      * or <code>null</code> if no such value exists.<p>
227      *
228      * @param name the key to get the content values for
229      * @param locale the locale to get the content values for
230      *
231      * @return the content value for the given key name
232      */

233     List JavaDoc getValues(String JavaDoc name, Locale JavaDoc locale);
234
235     /**
236      * Checks if the given locale exists in this XML document.<p>
237      *
238      * @param locale the locale to check
239      *
240      * @return true if the given locale exists in this XML document, false otherwise
241      */

242     boolean hasLocale(Locale JavaDoc locale);
243
244     /**
245      * Returns <code>true</code> if a value exists with the given key name,
246      * <code>false</code> otherwise.<p>
247      *
248      * You can provide an index for the value by appending a numer in aquare brackets
249      * to the name parameter like this "Title[1]".
250      * If no index is provided, 0 is used for the index position.<p>
251      *
252      * @param name the key to check
253      * @param locale the locale to check
254      *
255      * @return true if a value exists with the given key name, false otherwise
256      */

257     boolean hasValue(String JavaDoc name, Locale JavaDoc locale);
258
259     /**
260      * Returns <code>true</code> if a value exists with the given key name at the selected index,
261      * <code>false</code> otherwise.<p>
262      *
263      * @param name the key to check
264      * @param locale the locale to check
265      * @param index the index position to check
266      *
267      * @return true if a value exists with the given key name at the selected index,
268      * false otherwise
269      */

270     boolean hasValue(String JavaDoc name, Locale JavaDoc locale, int index);
271
272     /**
273      * Initializes this XML document, required after structural changes to the XML.<p>
274      *
275      * If nodes in the XML are added, removed or moved, the document needs to be initialized in
276      * order to update the internal data structures.<p>
277      */

278     void initDocument();
279
280     /**
281      * Returns <code>true</code> if a value exists with the given key name,
282      * and that value is enabled,
283      * <code>false</code> otherwise.<p>
284      *
285      * You can provide an index for the value by appending a numer in aquare brackets
286      * to the name parameter like this "Title[1]".
287      * If no index is provided, 0 is used for the index position.<p>
288      *
289      * @param name the key to check
290      * @param locale the locale to check
291      *
292      * @return true if a value exists with the given key name, and that value is enabled,
293      * false otherwise
294      */

295     boolean isEnabled(String JavaDoc name, Locale JavaDoc locale);
296
297     /**
298      * Returns <code>true</code> if a value exists with the given key name at the selected index,
299      * and that value is enabled,
300      * <code>false</code> otherwise.<p>
301      *
302      * @param name the key to check
303      * @param locale the locale to check
304      * @param index the index position to check
305      *
306      * @return true if a value exists with the given key name at the selected index,
307      * and that value is enabled, false otherwise
308      */

309     boolean isEnabled(String JavaDoc name, Locale JavaDoc locale, int index);
310
311     /**
312      * Moves the content of the given source locale to the given destination locale in this XML document.<p>
313      *
314      * @param source the source locale
315      * @param destination the destination locale
316      *
317      * @throws CmsXmlException in case either the source locale did not exist, or the destination locale already exists in the document, or if something else goes wrong
318      */

319     void moveLocale(Locale JavaDoc source, Locale JavaDoc destination) throws CmsXmlException;
320
321     /**
322      * Removes the given locale from this XML document.
323      *
324      * @param locale the locale to remove
325      *
326      * @throws CmsXmlException in case the locale did not exist in the document, or if something else goes wrong
327      */

328     void removeLocale(Locale JavaDoc locale) throws CmsXmlException;
329
330     /**
331      * Validates the content of this XML document.<p>
332      *
333      * @param cms the current OpenCms user context
334      *
335      * @return an error handler instance that provides information about the errors or warnings that have been found
336      */

337     CmsXmlContentErrorHandler validate(CmsObject cms);
338 }
Popular Tags