Java > Open Source Codes > org > opencms > xml > content > CmsXmlContent


1 /*
2  * File : $Source: /usr/local/cvs/opencms/src/org/opencms/xml/content/CmsXmlContent.java,v $
3  * Date : $Date: 2006/07/19 12:38:17 $
4  * Version: $Revision: 1.38 $
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.content;
33
34 import org.opencms.file.CmsFile;
35 import org.opencms.file.CmsObject;
36 import org.opencms.file.CmsResource;
37 import org.opencms.i18n.CmsEncoder;
38 import org.opencms.i18n.CmsLocaleManager;
39 import org.opencms.main.CmsIllegalArgumentException;
40 import org.opencms.main.CmsLog;
41 import org.opencms.main.CmsRuntimeException;
42 import org.opencms.staticexport.CmsLinkProcessor;
43 import org.opencms.staticexport.CmsLinkTable;
44 import org.opencms.xml.A_CmsXmlDocument;
45 import org.opencms.xml.CmsXmlContentDefinition;
46 import org.opencms.xml.CmsXmlException;
47 import org.opencms.xml.CmsXmlUtils;
48 import org.opencms.xml.I_CmsXmlDocument;
49 import org.opencms.xml.types.CmsXmlNestedContentDefinition;
50 import org.opencms.xml.types.I_CmsXmlContentValue;
51 import org.opencms.xml.types.I_CmsXmlSchemaType;
52
53 import java.io.IOException ;
54 import java.util.ArrayList ;
55 import java.util.Collections ;
56 import java.util.HashMap ;
57 import java.util.HashSet ;
58 import java.util.Iterator ;
59 import java.util.List ;
60 import java.util.Locale ;
61 import java.util.Set ;
62
63 import org.apache.commons.logging.Log;
64
65 import org.dom4j.Document;
66 import org.dom4j.Element;
67 import org.dom4j.Node;
68 import org.xml.sax.EntityResolver ;
69 import org.xml.sax.SAXException ;
70
71 /**
72  * Implementation of a XML content object,
73  * used to access and manage structured content.<p>
74  *
75  * Use the {@link org.opencms.xml.content.CmsXmlContentFactory} to generate an
76  * instance of this class.<p>
77  *
78  * @author Alexander Kandzior
79  *
80  * @version $Revision: 1.38 $
81  *
82  * @since 6.0.0
83  */
84 public class CmsXmlContent extends A_CmsXmlDocument implements I_CmsXmlDocument {
85
86     /** The property to set to enable xerces schema validation. */
87     public static final String XERCES_SCHEMA_PROPERTY = "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation";
88
89     /** The log object for this class. */
90     private static final Log LOG = CmsLog.getLog(CmsXmlContent.class);
91
92     /** The XML content definition object (i.e. XML schema) used by this content. */
93     protected CmsXmlContentDefinition m_contentDefinition;
94
95     /**
96      * Hides the public constructor.<p>
97      */
98     protected CmsXmlContent() {
99
100         // noop
101 }
102
103     /**
104      * Create a new XML content based on the given content definiton,
105      * that will have one language node for the given locale all initialized with default values.<p>
106      *
107      * The given encoding is used when marshalling the XML again later.<p>
108      *
109      * @param cms the current users OpenCms content
110      * @param locale the locale to generate the default content for
111      * @param encoding the encoding to use when marshalling the XML content later
112      * @param contentDefinition the content definiton to create the content for
113      */
114     protected CmsXmlContent(CmsObject cms, Locale locale, String encoding, CmsXmlContentDefinition contentDefinition) {
115
116         // content defition must be set here since it's used during document creation
117 m_contentDefinition = contentDefinition;
118         // create the XML document according to the content definition
119 Document document = contentDefinition.createDocument(cms, this, locale);
120         // initialize the XML content structure
121 initDocument(document, encoding, m_contentDefinition);
122     }
123
124     /**
125      * Creates a new XML content based on the provided XML document.<p>
126      *
127      * The given encoding is used when marshalling the XML again later.<p>
128      *
129      * @param document the document to create the xml content from
130      * @param encoding the encoding of the xml content
131      * @param resolver the XML entitiy resolver to use
132      */
133     protected CmsXmlContent(Document document, String encoding, EntityResolver resolver) {
134
135         // must set document first to be able to get the content definition
136 m_document = document;
137         // for the next line to work the document must already be available
138 m_contentDefinition = getContentDefinition(resolver);
139         // initialize the XML content structure
140 initDocument(m_document, encoding, m_contentDefinition);
141     }
142
143     /**
144      * @see org.opencms.xml.I_CmsXmlDocument#addLocale(org.opencms.file.CmsObject, java.util.Locale)
145      */
146     public void addLocale(CmsObject cms, Locale locale) throws CmsXmlException {
147
148         if (hasLocale(locale)) {
149             throw new CmsXmlException(org.opencms.xml.page.Messages.get().container(
150                 org.opencms.xml.page.Messages.ERR_XML_PAGE_LOCALE_EXISTS_1,
151                 locale));
152         }
153         // add element node for Locale
154 m_contentDefinition.createLocale(cms, this, m_document.getRootElement(), locale);
155         // re-initialize the bookmarks
156 initDocument(m_document, m_encoding, m_contentDefinition);
157     }
158
159     /**
160      * Adds a new XML content value for the given element name and locale at the given index position
161      * to this XML content document.<p>
162      *
163      * @param cms the current users OpenCms context
164      * @param path the path to the XML content value element
165      * @param locale the locale where to add the new value
166      * @param index the index where to add the value (relative to all other values of this type)
167      *
168      * @return the created XML content value
169      *
170      * @throws CmsIllegalArgumentException if the given path is invalid
171      * @throws CmsRuntimeException if the element identified by the path already occured {@link I_CmsXmlSchemaType#getMaxOccurs()}
172      * or the given <code>index</code> is invalid (too high).
173      */
174     public I_CmsXmlContentValue addValue(CmsObject cms, String path, Locale locale, int index)
175     throws CmsIllegalArgumentException, CmsRuntimeException {
176
177         // get the schema type of the requested path
178 I_CmsXmlSchemaType type = m_contentDefinition.getSchemaType(path);
179         if (type == null) {
180             throw new CmsIllegalArgumentException(Messages.get().container(
181                 Messages.ERR_XMLCONTENT_UNKNOWN_ELEM_PATH_SCHEMA_1,
182                 path));
183         }
184
185         Element parentElement;
186         String elementName;
187         CmsXmlContentDefinition contentDefinition;
188         if (CmsXmlUtils.isDeepXpath(path)) {
189             // this is a nested content definition, so the parent element must be in the bookmarks
190 String parentPath = CmsXmlUtils.removeLastXpathElement(path);
191             Object o = getBookmark(parentPath, locale);
192             if (o == null) {
193                 throw new CmsIllegalArgumentException(Messages.get().container(
194                     Messages.ERR_XMLCONTENT_UNKNOWN_ELEM_PATH_1,
195                     path));
196             }
197             CmsXmlNestedContentDefinition parentValue = (CmsXmlNestedContentDefinition)o;
198             parentElement = parentValue.getElement();
199             elementName = CmsXmlUtils.getLastXpathElement(path);
200             contentDefinition = parentValue.getNestedContentDefinition();
201         } else {
202             // the parent element is the locale element
203 parentElement = getLocaleNode(locale);
204             elementName = CmsXmlUtils.removeXpathIndex(path);
205             contentDefinition = m_contentDefinition;
206         }
207
208         // read the XML siblings from the parent node
209 List siblings = parentElement.elements(elementName);
210
211         int insertIndex;
212         if (siblings.size() > 0) {
213
214             if (siblings.size() >= type.getMaxOccurs()) {
215                 // must not allow adding an element if max occurs would be violated
216 throw new CmsRuntimeException(Messages.get().container(
217                     Messages.ERR_XMLCONTENT_ELEM_MAXOCCURS_2,
218                     elementName,
219                     new Integer (type.getMaxOccurs())));
220             }
221
222             if (index > siblings.size()) {
223                 // index position behind last element of the list
224 throw new CmsRuntimeException(Messages.get().container(
225                     Messages.ERR_XMLCONTENT_ADD_ELEM_INVALID_IDX_3,
226                     new Integer (index),
227                     new Integer (siblings.size())));
228             }
229
230             // check for offset required to append beyond last position
231 int offset = (index == siblings.size()) ? 1 : 0;
232             // get the element from the parent at the selected position
233 Element sibling = (Element)siblings.get(index - offset);
234             // check position of the node in the parent node content
235 insertIndex = sibling.getParent().content().indexOf(sibling) + offset;
236         } else {
237
238             if (index > 0) {
239                 // since the element does not occur, index must be 0
240 throw new CmsRuntimeException(Messages.get().container(
241                     Messages.ERR_XMLCONTENT_ADD_ELEM_INVALID_IDX_2,
242                     new Integer (index),
243                     elementName));
244             }
245
246             // check where in the type sequence the type should appear
247 int typeIndex = contentDefinition.getTypeSequence().indexOf(type);
248             if (typeIndex == 0) {
249                 // this is the first type, so we just add at the very first position
250 insertIndex = 0;
251             } else {
252
253                 // create a list of all element names that should occur before the selected type
254 List previousTypeNames = new ArrayList ();
255                 for (int i = 0; i < typeIndex; i++) {
256                     I_CmsXmlSchemaType t = (I_CmsXmlSchemaType)contentDefinition.getTypeSequence().get(i);
257                     previousTypeNames.add(t.getName());
258                 }
259
260                 // iterate all elements of the parent node
261 Iterator i = parentElement.content().iterator();
262                 int pos = 0;
263                 while (i.hasNext()) {
264                     Node node = (Node)i.next();
265                     if (node instanceof Element) {
266                         if (!previousTypeNames.contains(node.getName())) {
267                             // the element name is NOT in the list of names that occure before the selected type,
268 // so it must be an element that occurs AFTER the type
269 break;
270                         }
271                     }
272                     pos++;
273                 }
274                 insertIndex = pos;
275             }
276         }
277
278         // append the new element at the calculated position
279 I_CmsXmlContentValue newValue = addValue(cms, parentElement, type, locale, insertIndex);
280
281         // re-initialize this XML content
282 initDocument(m_document, m_encoding, m_contentDefinition);
283
284         // return the value instance that was stored in the bookmarks
285 // just returning "newValue" isn't enough since this instance is NOT stored in the bookmarks
286 return (I_CmsXmlContentValue)getBookmark(getBookmarkName(newValue.getPath(), locale));
287     }
288
289     /**
290      * @see org.opencms.xml.I_CmsXmlDocument#getContentDefinition()
291      */
292     public CmsXmlContentDefinition getContentDefinition() {
293
294         return m_contentDefinition;
295     }
296
297     /**
298      * @see org.opencms.xml.A_CmsXmlDocument#getLinkProcessor(org.opencms.file.CmsObject, org.opencms.staticexport.CmsLinkTable)
299      */
300     public CmsLinkProcessor getLinkProcessor(CmsObject cms, CmsLinkTable linkTable) {
301
302         // initialize link processor
303 String relativeRoot = null;
304         if (m_file != null) {
305             relativeRoot = CmsResource.getParentFolder(cms.getSitePath(m_file));
306         }
307         return new CmsLinkProcessor(cms, linkTable, getEncoding(), relativeRoot);
308     }
309
310     /**
311      * Returns the value sequence for the selected element name in this XML content.<p>
312      *
313      * If the given element name is not valid according to the schema of this XML content,
314      * <code>null</code> is returned.<p>
315      *
316      * @param name the element name (XML node name) to the the value sequence for
317      * @param locale the locale to get the value sequence for
318      *
319      * @return the value sequence for the selected element name in this XML content
320      */
321     public CmsXmlContentValueSequence getValueSequence(String name, Locale locale) {
322
323         I_CmsXmlSchemaType type = m_contentDefinition.getSchemaType(name);
324         if (type == null) {
325             return null;
326         }
327         return new CmsXmlContentValueSequence(name, type, locale, this);
328     }
329
330     /**
331      * Removes an existing XML content value of the given element name and locale at the given index position
332      * from this XML content document.<p>
333      *
334      * @param name the name of the XML content value element
335      * @param locale the locale where to remove the value
336      * @param index the index where to remove the value (relative to all other values of this type)
337      */
338     public void removeValue(String name, Locale locale, int index) {
339
340         // first get the value from the selected locale and index
341 I_CmsXmlContentValue value = getValue(name, locale, index);
342
343         // check for the min / max occurs constrains
344 List values = getValues(name, locale);
345         if (values.size() <= value.getMinOccurs()) {
346             // must not allow removing an element if min occurs would be violated
347 throw new CmsRuntimeException(Messages.get().container(
348                 Messages.ERR_XMLCONTENT_ELEM_MINOCCURS_2,
349                 name,
350                 new Integer (value.getMinOccurs())));
351         }
352
353         // detach the value node from the XML document
354 value.getElement().detach();
355
356         // re-initialize this XML content
357 initDocument(m_document, m_encoding, m_contentDefinition);
358
359     }
360
361     /**
362      * Resolves the mappings for all values of this XML content.<p>
363      *
364      * @param cms the current users OpenCms context
365      */
366     public void resolveMappings(CmsObject cms) {
367
368         // iterate through all initialized value nodes in this XML content
369 CmsXmlContentMappingVisitor visitor = new CmsXmlContentMappingVisitor(cms, this);
370         visitAllValuesWith(visitor);
371     }
372
373     /**
374      * @see org.opencms.xml.I_CmsXmlDocument#validate(org.opencms.file.CmsObject)
375      */
376     public CmsXmlContentErrorHandler validate(CmsObject cms) {
377
378         // iterate through all initialized value nodes in this XML content
379 CmsXmlContentValidationVisitor visitor = new CmsXmlContentValidationVisitor(cms);
380         visitAllValuesWith(visitor);
381
382         return visitor.getErrorHandler();
383     }
384
385     /**
386      * Visists all values of this XML content with the given value visitor.<p>
387      *
388      * Please note that the order in which the values are visited may NOT be the
389      * order they apper in the XML document. It is ensured that the the parent
390      * of a nested value is visited before the element it contains.<p>
391      *
392      * @param visitor the value visitor implementation to visit the values with
393      */
394     public void visitAllValuesWith(I_CmsXmlContentValueVisitor visitor) {
395
396         List bookmarks = new ArrayList (getBookmarks());
397         Collections.sort(bookmarks);
398
399         for (int i = 0; i < bookmarks.size(); i++) {
400
401             String key = (String )bookmarks.get(i);
402             I_CmsXmlContentValue value = (I_CmsXmlContentValue)getBookmark(key);
403             visitor.visit(value);
404         }
405     }
406
407     /**
408      * @see org.opencms.xml.A_CmsXmlDocument#getBookmark(java.lang.String)
409      */
410     protected Object getBookmark(String bookmark) {
411
412         // allows package classes to directly access the bookmark information of the XML content
413 return super.getBookmark(bookmark);
414     }
415
416     /**
417      * @see org.opencms.xml.A_CmsXmlDocument#getBookmarks()
418      */
419     protected Set getBookmarks() {
420
421         // allows package classes to directly access the bookmark information of the XML content
422 return super.getBookmarks();
423     }
424
425     /**
426      * Returns the XML root element node for the given locale.<p>
427      *
428      * @param locale the locale to get the root element for
429      *
430      * @return the XML root element node for the given locale
431      *
432      * @throws CmsRuntimeException if no language element is found in the document
433      */
434     protected Element getLocaleNode(Locale locale) throws CmsRuntimeException {
435
436         String localeStr = locale.toString();
437         Iterator i = m_document.getRootElement().elements().iterator();
438         while (i.hasNext()) {
439             Element element = (Element)i.next();
440             if (localeStr.equals(element.attributeValue(CmsXmlContentDefinition.XSD_ATTRIBUTE_VALUE_LANGUAGE))) {
441                 // language element found, return it
442 return element;
443             }
444         }
445
446         // language element was not found
447 throw new CmsRuntimeException(Messages.get().container(Messages.ERR_XMLCONTENT_MISSING_LOCALE_1, locale));
448     }
449
450     /**
451      * @see org.opencms.xml.A_CmsXmlDocument#initDocument(org.dom4j.Document, java.lang.String, org.opencms.xml.CmsXmlContentDefinition)
452      */
453     protected void initDocument(Document document, String encoding, CmsXmlContentDefinition definition) {
454
455         m_document = document;
456         m_contentDefinition = definition;
457         m_encoding = CmsEncoder.lookupEncoding(encoding, encoding);
458         m_elementLocales = new HashMap ();
459         m_elementNames = new HashMap ();
460         m_locales = new HashSet ();
461         clearBookmarks();
462
463         // initialize the bookmarks
464 for (Iterator i = m_document.getRootElement().elementIterator(); i.hasNext();) {
465             Element node = (Element)i.next();
466             try {
467                 Locale locale = CmsLocaleManager.getLocale(node.attribute(
468                     CmsXmlContentDefinition.XSD_ATTRIBUTE_VALUE_LANGUAGE).getValue());
469
470                 addLocale(locale);
471                 processSchemaNode(node, null, locale, definition);
472             } catch (NullPointerException e) {
473                 LOG.error(Messages.get().getBundle().key(Messages.LOG_XMLCONTENT_INIT_BOOKMARKS_0), e);
474             }
475         }
476
477     }
478
479     /**
480      * Sets the file this XML content is written to.<p>
481      *
482      * @param file the file this XML content content is written to
483      */
484     protected void setFile(CmsFile file) {
485
486         m_file = file;
487     }
488
489     /**
490      * Adds a new XML schema type with the default value to the given parent node.<p>
491      *
492      * @param cms the cms context
493      * @param parent the XML parent element to add the new value to
494      * @param type the type of the value to add
495      * @param locale the locale to add the new value for
496      * @param insertIndex the index in the XML document where to add the XML node
497      *
498      * @return the created XML content value
499      */
500     private I_CmsXmlContentValue addValue(
501         CmsObject cms,
502         Element parent,
503         I_CmsXmlSchemaType type,
504         Locale locale,
505         int insertIndex) {
506
507         // first generate the XML element for the new value
508 Element element = type.generateXml(cms, this, parent, locale);
509         // detatch the XML element from the appended position in order to insert it at the required position
510 element.detach();
511         // add the XML element at the required position in the parent XML node
512 parent.content().add(insertIndex, element);
513         // create the type and return it
514 I_CmsXmlContentValue value = type.createValue(this, element, locale);
515         // generate the default value again - required for nested mappings because only now the full path is available
516 String defaultValue = m_contentDefinition.getContentHandler().getDefault(cms, value, locale);
517         if (defaultValue != null) {
518             // only if there is a default value available use it to overwrite the initial default
519 value.setStringValue(cms, defaultValue);
520         }
521         // finally return the value
522 return value;
523     }
524
525     /**
526      * Returns the content definition object for this xml content object.<p>
527      *
528      * @param resolver the XML entity resolver to use, required for VFS access
529      *
530      * @return the content definition object for this xml content object
531      *
532      * @throws CmsRuntimeException if the schema location attribute (<code>systemId</code>)cannot be found,
533      * parsing of the schema fails, an underlying IOException occurs or unmarshalling fails
534      *
535      */
536     private CmsXmlContentDefinition getContentDefinition(EntityResolver resolver) throws CmsRuntimeException {
537
538         String schemaLocation = m_document.getRootElement().attributeValue(
539             I_CmsXmlSchemaType.XSI_NAMESPACE_ATTRIBUTE_NO_SCHEMA_LOCATION);
540         // Note regarding exception handling:
541 // Since this object already is a valid XML content object,
542 // it must have a valid schema, otherwise it would not exist.
543 // Therefore the exceptions should never be really thrown.
544 if (schemaLocation == null) {
545             throw new CmsRuntimeException(Messages.get().container(Messages.ERR_XMLCONTENT_MISSING_SCHEMA_0));
546         }
547
548             try {
549             return CmsXmlContentDefinition.unmarshal(schemaLocation, resolver);
550             } catch (SAXException e) {
551                 throw new CmsRuntimeException(Messages.get().container(Messages.ERR_XML_SCHEMA_PARSE_0), e);
552             } catch (IOException e) {
553                 throw new CmsRuntimeException(Messages.get().container(Messages.ERR_XML_SCHEMA_IO_0), e);
554             } catch (CmsXmlException e) {
555                 throw new CmsRuntimeException(Messages.get().container(Messages.ERR_XMLCONTENT_UNMARSHAL_0), e);
556             }
557         }
558
559     /**
560      * Processes a document node and extracts the values of the node according to the provided XML
561      * content definition.<p>
562      *
563      * @param root the root node element to process
564      * @param rootPath the Xpath of the root node in the document
565      * @param locale the locale
566      * @param definition the XML content definition to use for processing the values
567      */
568     private void processSchemaNode(Element root, String rootPath, Locale locale, CmsXmlContentDefinition definition) {
569
570         int count = 1;
571         String previousName = null;
572
573         // first remove all non-element node (i.e. white space text nodes)
574 List content = root.content();
575         for (int i = content.size() - 1; i >= 0; i--) {
576             Node node = (Node)content.get(i);
577             if (!(node instanceof Element)) {
578                 // this node is not an element, so it must be a white space text node, remove it
579 content.remove(i);
580             }
581         }
582
583         // iterate all elements again
584 for (Iterator i = root.content().iterator(); i.hasNext();) {
585
586             // node must be an element since all non-elements were removed
587 Element element = (Element)i.next();
588
589             // check if this is a new node, if so reset the node counter
590 String name = element.getName();
591             if ((previousName == null) || !previousName.equals(name)) {
592                 previousName = name;
593                 count = 1;
594             }
595
596             // build the Xpath expression for the current node
597 String path;
598             if (rootPath != null) {
599                 StringBuffer b = new StringBuffer (rootPath.length() + name.length() + 6);
600                 b.append(rootPath);
601                 b.append('/');
602                 b.append(CmsXmlUtils.createXpathElement(name, count));
603                 path = b.toString();
604             } else {
605                 path = CmsXmlUtils.createXpathElement(name, count);
606             }
607
608             // create a XML content value element
609 I_CmsXmlSchemaType schemaType = definition.getSchemaType(name);
610
611             if (schemaType != null) {
612                 // directly add simple type to schema
613 I_CmsXmlContentValue value = schemaType.createValue(this, element, locale);
614                 addBookmark(path, locale, true, value);
615
616                 if (!schemaType.isSimpleType()) {
617                     // recurse for nested schema
618 CmsXmlNestedContentDefinition nestedSchema = (CmsXmlNestedContentDefinition)schemaType;
619                     processSchemaNode(element, path, locale, nestedSchema.getNestedContentDefinition());
620                 }
621             } else {
622                 // unknown XML node name according to schema
623 if (LOG.isWarnEnabled()) {
624                     LOG.warn(Messages.get().getBundle().key(
625                         Messages.LOG_XMLCONTENT_INVALID_ELEM_2,
626                         name,
627                         definition.getSchemaLocation()));
628                 }
629             }
630
631             // increase the node counter
632 count++;
633         }
634     }
635 }

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags