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><xsd:element name="title" type="cmsStringType" minOccurs="0" maxOccurs="unbounded" default="Some text" /></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}