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.I_CmsXmlDocument; 032 033import java.util.Locale; 034 035import org.dom4j.Element; 036 037/** 038 * Provides access to the value of a specific XML content node.<p> 039 * 040 * @since 6.0.0 041 */ 042public interface I_CmsXmlContentValue extends I_CmsXmlSchemaType { 043 044 /** 045 * Search content configuration for the value. 046 * The configuration determines how the conent's value should be added to the indexed content fields. 047 */ 048 public static class CmsSearchContentConfig { 049 050 /** Configuration for not adding the value to the content fields. */ 051 public static final CmsSearchContentConfig FALSE = new CmsSearchContentConfig(SearchContentType.FALSE, null); 052 /** Configuration for adding the extraction of the content linked by the value to the content fields. */ 053 public static final CmsSearchContentConfig CONTENT = new CmsSearchContentConfig( 054 SearchContentType.CONTENT, 055 null); 056 /** Configuration for adding the value unchanged to the content fields. */ 057 public static final CmsSearchContentConfig TRUE = new CmsSearchContentConfig(SearchContentType.TRUE, null); 058 /** The search content type. */ 059 private SearchContentType m_type; 060 /** The adjustment implementation for the value. */ 061 private String m_adjustmentClass; 062 063 /** 064 * Constructs a new search content configuration. 065 * @param type the search content type 066 * @param adjustmentClass the adjustment implementation 067 */ 068 private CmsSearchContentConfig(SearchContentType type, String adjustmentClass) { 069 070 m_type = type; 071 m_adjustmentClass = adjustmentClass; 072 } 073 074 /** 075 * Returns the configuration for the search content type. 076 * @param searchContentType the type to get the configuration for 077 * @return the configuration for the type 078 */ 079 public static CmsSearchContentConfig get(SearchContentType searchContentType) { 080 081 return get(searchContentType, null); 082 } 083 084 /** 085 * Returns the configuration for the combination of search content type and adjustment class. 086 * @param searchContentType the type to get the configuration for 087 * @param adjustmentClass the adjustment class 088 * @return the configuration for the type/adjustment combination. 089 */ 090 public static CmsSearchContentConfig get(SearchContentType searchContentType, String adjustmentClass) { 091 092 if (searchContentType == null) { 093 return adjustmentClass == null 094 ? null 095 : new CmsSearchContentConfig(SearchContentType.TRUE, adjustmentClass); 096 } 097 switch (searchContentType) { 098 case FALSE: 099 return FALSE; 100 case TRUE: 101 return adjustmentClass == null 102 ? TRUE 103 : new CmsSearchContentConfig(SearchContentType.TRUE, adjustmentClass); 104 case CONTENT: 105 return CONTENT; 106 default: 107 return null; 108 } 109 } 110 111 /** 112 * @return the adjustment class. 113 */ 114 public String getAdjustmentClass() { 115 116 return m_adjustmentClass; 117 } 118 119 /** 120 * @return the search content type. 121 */ 122 public SearchContentType getSearchContentType() { 123 124 return m_type; 125 } 126 } 127 128 /** 129 * The available search types for element searchsetting. 130 */ 131 public static enum SearchContentType { 132 133 /** Do not merge the value of the field into the content field. */ 134 FALSE, 135 /** Merge the value of the field into the content field. */ 136 TRUE, 137 /** Merge the extracted content of the resource linked by the element into the content field. */ 138 CONTENT; 139 140 /** 141 * Converts the String into a SearchContentType. Returns <code>null</code> if conversion is not possible. 142 * @param type the search content type as String. 143 * @return the search content type specified by the provided String, or <code>null</code> if the String did not specify any search content type. 144 */ 145 public static SearchContentType fromString(String type) { 146 147 if (null == type) { 148 return null; 149 } 150 switch (type.toLowerCase()) { 151 case "false": 152 return FALSE; 153 case "true": 154 return TRUE; 155 case "content": 156 return CONTENT; 157 default: 158 return null; 159 } 160 } 161 162 } 163 164 /** 165 * Returns the XML content instance this value belongs to.<p> 166 * 167 * @return the XML content instance this value belongs to 168 */ 169 I_CmsXmlDocument getDocument(); 170 171 /** 172 * Returns the original XML element of this XML content value.<p> 173 * 174 * @return the original XML element of this XML content value 175 */ 176 Element getElement(); 177 178 /** 179 * Returns the node index of this XML content value in the source XML document, 180 * starting with 0, with special handling of elements in choice groups.<p> 181 * 182 * This is useful in case there are more than one elements 183 * with the same XML node name in the source XML document.<p> 184 * 185 * Elements in XML choice groups will share the same number space, so a choice 186 * sequence will be numbered like this: 187 * <code>Title[1], Text[2], Title[3], Image[4]</code><p> 188 * 189 * @return the index of this XML content node in the source document with special handling of elements in choice groups 190 * 191 * @see #getXmlIndex() 192 */ 193 int getIndex(); 194 195 /** 196 * Returns the locale of this XML content value was generated for.<p> 197 * 198 * @return the locale of this XML content value was generated for 199 */ 200 Locale getLocale(); 201 202 /** 203 * Returns the total number of XML elements of this type that currently exist in the source document.<p> 204 * 205 * @return the total number of XML elements of this type that currently exist in the source document 206 */ 207 int getMaxIndex(); 208 209 /** 210 * Returns the path of this XML content value in the source document.<p> 211 * 212 * @return the path of this XML content value in the source document 213 */ 214 String getPath(); 215 216 /** 217 * Returns the value of this XML content node as a plain text String.<p> 218 * 219 * Plain text in this context means a pure textual representation 220 * of the content (i.e. without html tags). 221 * The plain text may be <code>null</code>, too, if there is no sound or useful 222 * textual representation (i.e. color values).<p> 223 * 224 * @param cms an initialized instance of a CmsObject 225 * 226 * @return the value of this XML content node as a plain text String 227 */ 228 String getPlainText(CmsObject cms); 229 230 /** 231 * Returns the search content type for the value. Default implementation uses the historic isSearchable() method. 232 * @return the search content type 233 */ 234 default CmsSearchContentConfig getSearchContentConfig() { 235 236 return new CmsSearchContentConfig(isSearchable() ? SearchContentType.TRUE : SearchContentType.FALSE, null); 237 } 238 239 /** 240 * Returns the value of this XML content node as a String.<p> 241 * 242 * @param cms an initialized instance of a CmsObject 243 * 244 * @return the value of this XML content node as a String 245 */ 246 String getStringValue(CmsObject cms); 247 248 /** 249 * Returns the node index of this XML content value in the source XML document, 250 * starting with 0, based on the XML ordering.<p> 251 * 252 * Elements in choice groups will be numbered like this: 253 * <code>Title[1], Text[1], Title[2], Image[1]</code><p> 254 * 255 * @return the index of this XML content node in the source document with special handling of elements in choice groups 256 * 257 * @see #getIndex() 258 */ 259 int getXmlIndex(); 260 261 /** 262 * Returns <code>true</code> in case this value is searchable by default with 263 * the integrated full text search.<p> 264 * 265 * @return <code>true</code> in case this value is searchable by default 266 */ 267 boolean isSearchable(); 268 269 /** 270 * Moves this XML content value one position down in the source document, if possible.<p> 271 * 272 * If the XML content value is already the first in it's sequence, it is not moved.<p> 273 */ 274 void moveDown(); 275 276 /** 277 * Moves this XML content value one position up in the source document, if possible.<p> 278 * 279 * If the XML content value is already the last in it's sequence, it is not moved.<p> 280 */ 281 void moveUp(); 282 283 /** 284 * Sets the provided String as value of this XML content node.<p> 285 * 286 * This method does provide processing of the content based on the 287 * users current OpenCms context. This can be used e.g. for link 288 * extraction and replacement in the content.<p> 289 * 290 * @param cms an initialized instance of a CmsObject 291 * @param value the value to set 292 * 293 */ 294 void setStringValue(CmsObject cms, String value); 295}