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  ;
42  import java.util.Locale  ;
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   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   source, Locale   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   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   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   name, Locale   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   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   getLocales(String   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   getNames(Locale   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   getStringValue(CmsObject cms, String   name, Locale   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   getStringValue(CmsObject cms, String   name, Locale   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   name, Locale   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   name, Locale   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   getValues(Locale   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   getValues(String   name, Locale   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   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   name, Locale   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   name, Locale   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   name, Locale   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   name, Locale   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   source, Locale   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   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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags