001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.xml.types;
029
030import org.opencms.file.CmsObject;
031import org.opencms.xml.CmsXmlContentDefinition;
032import org.opencms.xml.I_CmsXmlDocument;
033
034import java.util.Locale;
035
036import org.dom4j.Element;
037import org.dom4j.Namespace;
038import org.dom4j.QName;
039
040/**
041 * Describes a type in an OpenCms XML schema based content definition.<p>
042 *
043 * A XML content definition in OpenCms basically consists of a sequence of
044 * nodes in the following format:<p>
045 *
046 * <code>&lt;xsd:element name="title" type="cmsStringType" minOccurs="0" maxOccurs="unbounded" default="Some text" /&gt;</code>.<p>
047 *
048 * Internally, each configured element in a XML schema is represented by an instance of
049 * this interface. This allows for constructing or changing the XML schema through the
050 * provided API.<p>
051 *
052 * Note that this class only <i>describes the definition</i> of a value in the XML schema.
053 * It is not the representation of an actual value from a XML file,
054 * for this you need an instance of a {@link org.opencms.xml.types.I_CmsXmlContentValue}.<p>
055 *
056 * @since 6.0.0
057 *
058 * @see org.opencms.xml.types.I_CmsXmlContentValue
059 */
060public interface I_CmsXmlSchemaType extends Comparable<I_CmsXmlSchemaType> {
061
062    /** The schema instance namespace. */
063    Namespace XSI_NAMESPACE = Namespace.get("xsi", "http://www.w3.org/2001/XMLSchema-instance");
064
065    /** Constant for the XML schema attribute "noNamespaceSchemaLocation" in the XML schema instance namespace. */
066    QName XSI_NAMESPACE_ATTRIBUTE_NO_SCHEMA_LOCATION = QName.get("noNamespaceSchemaLocation", XSI_NAMESPACE);
067
068    /**
069     * Appends an XML representation of this schema type to the given XML element.<p>
070     *
071     * This is used to dynamically build a XML schema from an instance of a
072     * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
073     *
074     * @param root the element to append the XML to
075     */
076    void appendXmlSchema(Element root);
077
078    /**
079     * Creates a XML content value object for this type.<p>
080     *
081     * @param document the XML content instance this value belongs to
082     * @param element the XML element to create the value from
083     * @param locale the locale to create the value for
084     *
085     * @return the created XML content value object
086     */
087    I_CmsXmlContentValue createValue(I_CmsXmlDocument document, Element element, Locale locale);
088
089    /**
090     * Appends an XML for a new, empty node of this schema type to the given root element.<p>
091     *
092     * This is used to dynamically build a vaild XML content object from an initialized
093     * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
094     *
095     * Important: This method can only be used during initialization of a XML content object,
096     * not to add values to an already initialized XML content. To add values after initialization,
097     * use {@link org.opencms.xml.content.CmsXmlContent#addValue(CmsObject, String, Locale, int)}.<p>
098     *
099     * @param cms the current users OpenCms context
100     * @param document the document the XML is generated for
101     * @param root the element to append the XML to
102     * @param locale the locale to generate the element default content for
103     *
104     * @return the generated XML element
105     */
106    Element generateXml(CmsObject cms, I_CmsXmlDocument document, Element root, Locale locale);
107
108    /**
109     * Returns the maximum occurrences of choice options for this type in the current schema.<p>
110     *
111     * This will be greater than 0 only if {@link #isChoiceType()} is <code>true</code>.<p>
112     *
113     * @return the maximum occurrences of choice options for this type in the current schema
114     */
115    int getChoiceMaxOccurs();
116
117    /**
118     * Returns the content definition this schema type belongs to.<p>
119     *
120     * If the value belongs to a nested content, then the nested content definition is returned.
121     * This means that for documents with nested schemas, the content definition of a
122     * value is not necessarily equal to the content definition of the document itself,
123     * which can be obtained using {@link I_CmsXmlContentValue#getDocument()}.<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 occurrences of this type in the current schema.<p>
142     *
143     * @return the maximum occurrences of this type in the current schema
144     */
145    int getMaxOccurs();
146
147    /**
148     * Returns the minimum occurrences of this type in the current schema.<p>
149     *
150     * @return the minimum occurrences 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 type is an option inside of a choice sequence.<p>
188     *
189     * This method is intended to check if this type is a node inside a choice sequence.
190     * In order to check if this type defines a choice sequence, use {@link #isChoiceType()}.<p>
191     *
192     * @return <code>true</code> if this node defines a choice sequence
193     */
194    boolean isChoiceOption();
195
196    /**
197     * Returns <code>true</code> if this type defines a choice sequence.<p>
198     *
199     * This method is intended to check if this type is a node defining a choice sequence.
200     * In order to check if this type is an option inside of a choice sequence, use {@link #isChoiceOption()}.<p>
201     *
202     * @return <code>true</code> if this node defines a choice sequence
203     */
204    boolean isChoiceType();
205
206    /**
207     * Returns <code>true</code> if this is a simple type, or <code>false</code>
208     * if this type is a nested schema.<p>
209     *
210     * If a value is a nested schema, it must be an instance of {@link CmsXmlNestedContentDefinition}.<p>
211     *
212     * @return true if this is  a simple type, or false if this type is a nested schema
213     *
214     * @see CmsXmlNestedContentDefinition
215     */
216    boolean isSimpleType();
217
218    /**
219     * Creates a new instance of this XML schema type initialized with the given values.<p>
220     *
221     * @param name the name to use in the xml document
222     * @param minOccurs minimum number of occurrences
223     * @param maxOccurs maximum number of occurrences
224     *
225     * @return a new instance of this XML content type initialized with the given values
226     */
227    I_CmsXmlSchemaType newInstance(String name, String minOccurs, String maxOccurs);
228
229    /**
230     * Sets the content definition this schema type belongs to.<p>
231     *
232     * This is done automatically when the scheme type is added
233     * to a content definition. Usually there is no need to call this
234     * method from the application.<p>
235     *
236     * @param contentDefinition the content definition to set
237     */
238    void setContentDefinition(CmsXmlContentDefinition contentDefinition);
239
240    /**
241     * Sets the default value for a node of this type in the current schema.<p>
242     *
243     * @param defaultValue the default value to set
244     */
245    void setDefault(String defaultValue);
246
247    /**
248     * Checks if a given value is valid according to the validation rule (regular expression) used for validation
249     * of this schema type in the XML schema.<p>
250     *
251     * To have a more refined validation according to the special requirements of the
252     * content type, use custom validation rules in the appinfo which are
253     * processed with {@link org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)}.<p>
254     *
255     * @param value the value to validate
256     *
257     * @return the validation rule (regular expression) used for this schema type in the XML schema
258     *
259     * @see org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)
260     */
261    boolean validateValue(String value);
262}