I_CmsXmlSchemaType


1   /*
2    * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/xml/types/I_CmsXmlSchemaType.java,v $
3    * Date   : $Date: 2005/06/27 10:27:15 $
4    * Version: $Revision: 1.22 $
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.types;
33  
34  import org.opencms.file.CmsObject;
35  import org.opencms.xml.CmsXmlContentDefinition;
36  import org.opencms.xml.I_CmsXmlDocument;
37  
38  import java.util.Locale  ;
39  
40  import org.dom4j.Element;
41  import org.dom4j.Namespace;
42  import org.dom4j.QName;
43  
44  /**
45   * Describes a type in an OpenCms XML schema based content definition.<p>
46   *
47   * A XML content definition in OpenCms basically consists of a sequence of
48   * nodes in the following format:<p>
49   * 
50   * <code>&lt;xsd:element name="title" type="cmsStringType" minOccurs="0" maxOccurs="unbounded" default="Some text" /&gt;</code>.<p>
51   *
52   * Internally, each configured element in a XML schema is represented by an instance of 
53   * this interface. This allows for constructing or changing the XML schema through the 
54   * provided API.<p>
55   * 
56   * Note that this class only <i>describes the definition</i> of a value in the XML schema.
57   * It is not the representation of an actual value from a XML file,
58   * for this you need an instance of a {@link org.opencms.xml.types.I_CmsXmlContentValue}.<p>
59   *
60   * @author Alexander Kandzior 
61   * 
62   * @version $Revision: 1.22 $ 
63   * 
64   * @since 6.0.0 
65   * 
66   * @see org.opencms.xml.types.I_CmsXmlContentValue
67   */
68  public interface I_CmsXmlSchemaType extends Comparable   {
69  
70      /** The schema instance namespace. */
71      Namespace XSI_NAMESPACE = Namespace.get("xsi", "http://www.w3.org/2001/XMLSchema-instance");
72  
73      /** Constant for the XML schema attribute "noNamespaceSchemaLocation" in the XML schema instance namespace. */
74      QName XSI_NAMESPACE_ATTRIBUTE_NO_SCHEMA_LOCATION = QName.get("noNamespaceSchemaLocation", XSI_NAMESPACE);
75  
76      /**
77       * Appends an XML representation of this schema type to the given XML element.<p>
78       * 
79       * This is used to dynamically build a XML schema from an instance of a
80       * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
81       * 
82       * @param root the element to append the XML to
83       */
84      void appendXmlSchema(Element root);
85  
86      /**
87       * Creates a XML content value object for this type.<p>
88       * 
89       * @param document the XML content instance this value belongs to
90       * @param element the XML element to create the value from
91       * @param locale the locale to create the value for
92       * 
93       * @return the created XML content value object
94       */
95      I_CmsXmlContentValue createValue(I_CmsXmlDocument document, Element element, Locale   locale);
96  
97      /**
98       * Appends an XML for a new, empty node of this schema type to the given root element.<p>
99       * 
100      * This is used to dynamically build a vaild XML content object from an initialized
101      * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
102      * 
103      * Important: This method can only be used during initialization of a XML content object,
104      * not to add values to an already initialized XML content. To add values after initialization,
105      * use {@link org.opencms.xml.content.CmsXmlContent#addValue(CmsObject, String, Locale, int)}.<p>
106      * 
107      * @param cms the current users OpenCms context
108      * @param document the document the XML is generated for
109      * @param root the element to append the XML to
110      * @param locale the locale to generate the element default content for
111      * 
112      * @return the generated XML element
113      */
114     Element generateXml(CmsObject cms, I_CmsXmlDocument document, Element root, Locale   locale);
115 
116     /**
117      * Returns the content definition this schema type belongs to.<p> 
118      * 
119      * Note that for nested schemas, the content definition of a nested 
120      * value is not neccessarily equal to the content defintion of the document
121      * returned by {@link I_CmsXmlContentValue#getDocument()}. If the value belongs to a nested
122      * content, then the content definiton of the value also is the nested 
123      * content defintion.<p>
124      * 
125      * @return the content definition this schema type belongs to
126      */
127     CmsXmlContentDefinition getContentDefinition();
128 
129     /**
130      * Returns the default value for a node of this type in the current schema.<p>
131      * 
132      * @param locale the locale to generate the default value for
133      * 
134      * @return the default value for a node of this type in the current schema
135      * 
136      * @see org.opencms.xml.content.I_CmsXmlContentHandler#getDefault(CmsObject, I_CmsXmlContentValue, Locale)
137      */
138     String   getDefault(Locale   locale);
139 
140     /**
141      * Returns the maximum occurences of this type in the current schema.<p>
142      *
143      * @return the maximum occurences of this type in the current schema
144      */
145     int getMaxOccurs();
146 
147     /**
148      * Returns the minimum occurences of this type in the current schema.<p>
149      *
150      * @return the minimum occurences of this type in the current schema
151      */
152     int getMinOccurs();
153 
154     /**
155      * Returns the XML element node name of this type in the current schema.<p>
156      *
157      * The XML element node name can be configured in the schema.
158      * For example, the node name could be <code>"Title"</code>,
159      * <code>"Teaser"</code> or <code>"Text"</code>. The XML schema controls 
160      * what node names are allowed.<p> 
161      *
162      * @return the XML node name of this type in the current schema
163      */
164     String   getName();
165 
166     /**
167      * Returns a String representation of the XML definition for this schema type.<p>  
168      * 
169      * @return a String representation of the XML definition for this schema type
170      */
171     String   getSchemaDefinition();
172 
173     /**
174      * Returns the schema type name.<p>
175      *
176      * By convention, a XML schema type name has the form 
177      * <code>"OpenCms + ${name}"</code>. Examples are
178      * <code>"OpenCmsString"</code> or <code>"OpenCmsBoolean"</code>.<p>
179      * 
180      * The schema type name is fixed by the implementation.<p> 
181      *
182      * @return the schema type name
183      */
184     String   getTypeName();
185 
186     /**
187      * Returns <code>true</code> if this is a simple type, or <code>false</code>
188      * if this type is a nested schema.<p>
189      * 
190      * If a value is a nested schema, it must be an instance of {@link CmsXmlNestedContentDefinition}.<p> 
191      * 
192      * @return true if this is  a simple type, or false if this type is a nested schema
193      * 
194      * @see CmsXmlNestedContentDefinition
195      */
196     boolean isSimpleType();
197 
198     /**
199      * Creates a new instance of this XML schema type initialized with the given values.<p>
200      * 
201      * @param name the name to use in the xml document
202      * @param minOccurs minimum number of occurences
203      * @param maxOccurs maximum number of occurences
204      * 
205      * @return a new instance of this XML content type initialized with the given values
206      */
207     I_CmsXmlSchemaType newInstance(String   name, String   minOccurs, String   maxOccurs);
208 
209     /**
210      * Sets the content definition this schema type belongs to.<p>
211      * 
212      * This is done automatically when the scheme type is added
213      * to a content definition. Usually there is no need to call this 
214      * method from the application.<p>
215      * 
216      * @param contentDefinition the content definition to set
217      */
218     void setContentDefinition(CmsXmlContentDefinition contentDefinition);
219 
220     /**
221      * Sets the default value for a node of this type in the current schema.<p>
222      * 
223      * @param defaultValue the default value to set
224      */
225     void setDefault(String   defaultValue);
226 
227     /**
228      * Checks if a given value is valid according to the validation rule (regular expression) used for validation
229      * of this schema type in the XML schema.<p>
230      * 
231      * To have a more refined validation according to the special requirements of the
232      * content type, use custom validation rules in the appinfo which are
233      * processed with {@link org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)}.<p>
234      * 
235      * @param value the value to validate
236      * 
237      * @return the validation rule (regular expression) used for this schema type in the XML schema
238      * 
239      * @see org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)
240      */
241     boolean validateValue(String   value);
242 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags