001: /*
002: * File : $Source: /usr/local/cvs/opencms/src/org/opencms/xml/types/I_CmsXmlSchemaType.java,v $
003: * Date : $Date: 2008-02-27 12:05:29 $
004: * Version: $Revision: 1.25 $
005: *
006: * This library is part of OpenCms -
007: * the Open Source Content Management System
008: *
009: * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
010: *
011: * This library is free software; you can redistribute it and/or
012: * modify it under the terms of the GNU Lesser General Public
013: * License as published by the Free Software Foundation; either
014: * version 2.1 of the License, or (at your option) any later version.
015: *
016: * This library is distributed in the hope that it will be useful,
017: * but WITHOUT ANY WARRANTY; without even the implied warranty of
018: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: * Lesser General Public License for more details.
020: *
021: * For further information about Alkacon Software GmbH, please see the
022: * company website: http://www.alkacon.com
023: *
024: * For further information about OpenCms, please see the
025: * project website: http://www.opencms.org
026: *
027: * You should have received a copy of the GNU Lesser General Public
028: * License along with this library; if not, write to the Free Software
029: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
030: */
031:
032: package org.opencms.xml.types;
033:
034: import org.opencms.file.CmsObject;
035: import org.opencms.xml.CmsXmlContentDefinition;
036: import org.opencms.xml.I_CmsXmlDocument;
037:
038: import java.util.Locale;
039:
040: import org.dom4j.Element;
041: import org.dom4j.Namespace;
042: import org.dom4j.QName;
043:
044: /**
045: * Describes a type in an OpenCms XML schema based content definition.<p>
046: *
047: * A XML content definition in OpenCms basically consists of a sequence of
048: * nodes in the following format:<p>
049: *
050: * <code><xsd:element name="title" type="cmsStringType" minOccurs="0" maxOccurs="unbounded" default="Some text" /></code>.<p>
051: *
052: * Internally, each configured element in a XML schema is represented by an instance of
053: * this interface. This allows for constructing or changing the XML schema through the
054: * provided API.<p>
055: *
056: * Note that this class only <i>describes the definition</i> of a value in the XML schema.
057: * It is not the representation of an actual value from a XML file,
058: * for this you need an instance of a {@link org.opencms.xml.types.I_CmsXmlContentValue}.<p>
059: *
060: * @author Alexander Kandzior
061: *
062: * @version $Revision: 1.25 $
063: *
064: * @since 6.0.0
065: *
066: * @see org.opencms.xml.types.I_CmsXmlContentValue
067: */
068: public interface I_CmsXmlSchemaType extends Comparable {
069:
070: /** The schema instance namespace. */
071: Namespace XSI_NAMESPACE = Namespace.get("xsi",
072: "http://www.w3.org/2001/XMLSchema-instance");
073:
074: /** Constant for the XML schema attribute "noNamespaceSchemaLocation" in the XML schema instance namespace. */
075: QName XSI_NAMESPACE_ATTRIBUTE_NO_SCHEMA_LOCATION = QName.get(
076: "noNamespaceSchemaLocation", XSI_NAMESPACE);
077:
078: /**
079: * Appends an XML representation of this schema type to the given XML element.<p>
080: *
081: * This is used to dynamically build a XML schema from an instance of a
082: * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
083: *
084: * @param root the element to append the XML to
085: */
086: void appendXmlSchema(Element root);
087:
088: /**
089: * Creates a XML content value object for this type.<p>
090: *
091: * @param document the XML content instance this value belongs to
092: * @param element the XML element to create the value from
093: * @param locale the locale to create the value for
094: *
095: * @return the created XML content value object
096: */
097: I_CmsXmlContentValue createValue(I_CmsXmlDocument document,
098: Element element, Locale locale);
099:
100: /**
101: * Appends an XML for a new, empty node of this schema type to the given root element.<p>
102: *
103: * This is used to dynamically build a vaild XML content object from an initialized
104: * {@link org.opencms.xml.CmsXmlContentDefinition} class.<p>
105: *
106: * Important: This method can only be used during initialization of a XML content object,
107: * not to add values to an already initialized XML content. To add values after initialization,
108: * use {@link org.opencms.xml.content.CmsXmlContent#addValue(CmsObject, String, Locale, int)}.<p>
109: *
110: * @param cms the current users OpenCms context
111: * @param document the document the XML is generated for
112: * @param root the element to append the XML to
113: * @param locale the locale to generate the element default content for
114: *
115: * @return the generated XML element
116: */
117: Element generateXml(CmsObject cms, I_CmsXmlDocument document,
118: Element root, Locale locale);
119:
120: /**
121: * Returns the content definition this schema type belongs to.<p>
122: *
123: * If the value belongs to a nested content, then the nested content definition is returned.
124: * This means that for documents with nested schemas, the content definition of a
125: * value is not necessarily equal to the content definition of the document itself,
126: * which can be obtained using {@link I_CmsXmlContentValue#getDocument()}.<p>
127: *
128: * @return the content definition this schema type belongs to
129: */
130: CmsXmlContentDefinition getContentDefinition();
131:
132: /**
133: * Returns the default value for a node of this type in the current schema.<p>
134: *
135: * @param locale the locale to generate the default value for
136: *
137: * @return the default value for a node of this type in the current schema
138: *
139: * @see org.opencms.xml.content.I_CmsXmlContentHandler#getDefault(CmsObject, I_CmsXmlContentValue, Locale)
140: */
141: String getDefault(Locale locale);
142:
143: /**
144: * Returns the maximum occurences of this type in the current schema.<p>
145: *
146: * @return the maximum occurences of this type in the current schema
147: */
148: int getMaxOccurs();
149:
150: /**
151: * Returns the minimum occurences of this type in the current schema.<p>
152: *
153: * @return the minimum occurences of this type in the current schema
154: */
155: int getMinOccurs();
156:
157: /**
158: * Returns the XML element node name of this type in the current schema.<p>
159: *
160: * The XML element node name can be configured in the schema.
161: * For example, the node name could be <code>"Title"</code>,
162: * <code>"Teaser"</code> or <code>"Text"</code>. The XML schema controls
163: * what node names are allowed.<p>
164: *
165: * @return the XML node name of this type in the current schema
166: */
167: String getName();
168:
169: /**
170: * Returns a String representation of the XML definition for this schema type.<p>
171: *
172: * @return a String representation of the XML definition for this schema type
173: */
174: String getSchemaDefinition();
175:
176: /**
177: * Returns the schema type name.<p>
178: *
179: * By convention, a XML schema type name has the form
180: * <code>"OpenCms + ${name}"</code>. Examples are
181: * <code>"OpenCmsString"</code> or <code>"OpenCmsBoolean"</code>.<p>
182: *
183: * The schema type name is fixed by the implementation.<p>
184: *
185: * @return the schema type name
186: */
187: String getTypeName();
188:
189: /**
190: * Returns <code>true</code> if this is a simple type, or <code>false</code>
191: * if this type is a nested schema.<p>
192: *
193: * If a value is a nested schema, it must be an instance of {@link CmsXmlNestedContentDefinition}.<p>
194: *
195: * @return true if this is a simple type, or false if this type is a nested schema
196: *
197: * @see CmsXmlNestedContentDefinition
198: */
199: boolean isSimpleType();
200:
201: /**
202: * Creates a new instance of this XML schema type initialized with the given values.<p>
203: *
204: * @param name the name to use in the xml document
205: * @param minOccurs minimum number of occurences
206: * @param maxOccurs maximum number of occurences
207: *
208: * @return a new instance of this XML content type initialized with the given values
209: */
210: I_CmsXmlSchemaType newInstance(String name, String minOccurs,
211: String maxOccurs);
212:
213: /**
214: * Sets the content definition this schema type belongs to.<p>
215: *
216: * This is done automatically when the scheme type is added
217: * to a content definition. Usually there is no need to call this
218: * method from the application.<p>
219: *
220: * @param contentDefinition the content definition to set
221: */
222: void setContentDefinition(CmsXmlContentDefinition contentDefinition);
223:
224: /**
225: * Sets the default value for a node of this type in the current schema.<p>
226: *
227: * @param defaultValue the default value to set
228: */
229: void setDefault(String defaultValue);
230:
231: /**
232: * Checks if a given value is valid according to the validation rule (regular expression) used for validation
233: * of this schema type in the XML schema.<p>
234: *
235: * To have a more refined validation according to the special requirements of the
236: * content type, use custom validation rules in the appinfo which are
237: * processed with {@link org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)}.<p>
238: *
239: * @param value the value to validate
240: *
241: * @return the validation rule (regular expression) used for this schema type in the XML schema
242: *
243: * @see org.opencms.xml.content.I_CmsXmlContentHandler#resolveValidation(CmsObject, I_CmsXmlContentValue, org.opencms.xml.content.CmsXmlContentErrorHandler)
244: */
245: boolean validateValue(String value);
246: }
|