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 * The available search types for element searchsetting. 046 */ 047 public static enum SearchContentType { 048 /** Do not merge the value of the field into the content field. */ 049 FALSE, 050 /** Merge the value of the field into the content field. */ 051 TRUE, 052 /** Merge the extracted content of the resource linked by the element into the content field. */ 053 CONTENT; 054 055 /** 056 * Converts the String into a SearchContentType. Returns <code>null</code> if conversion is not possible. 057 * @param type the search content type as String. 058 * @return the search content type specified by the provided String, or <code>null</code> if the String did not specify any search content type. 059 */ 060 public static SearchContentType fromString(String type) { 061 062 if (null == type) { 063 return null; 064 } 065 switch (type.toLowerCase()) { 066 case "false": 067 return FALSE; 068 case "true": 069 return TRUE; 070 case "content": 071 return CONTENT; 072 default: 073 return null; 074 } 075 } 076 } 077 078 /** 079 * Returns the XML content instance this value belongs to.<p> 080 * 081 * @return the XML content instance this value belongs to 082 */ 083 I_CmsXmlDocument getDocument(); 084 085 /** 086 * Returns the original XML element of this XML content value.<p> 087 * 088 * @return the original XML element of this XML content value 089 */ 090 Element getElement(); 091 092 /** 093 * Returns the node index of this XML content value in the source XML document, 094 * starting with 0, with special handling of elements in choice groups.<p> 095 * 096 * This is useful in case there are more than one elements 097 * with the same XML node name in the source XML document.<p> 098 * 099 * Elements in XML choice groups will share the same number space, so a choice 100 * sequence will be numbered like this: 101 * <code>Title[1], Text[2], Title[3], Image[4]</code><p> 102 * 103 * @return the index of this XML content node in the source document with special handling of elements in choice groups 104 * 105 * @see #getXmlIndex() 106 */ 107 int getIndex(); 108 109 /** 110 * Returns the locale of this XML content value was generated for.<p> 111 * 112 * @return the locale of this XML content value was generated for 113 */ 114 Locale getLocale(); 115 116 /** 117 * Returns the total number of XML elements of this type that currently exist in the source document.<p> 118 * 119 * @return the total number of XML elements of this type that currently exist in the source document 120 */ 121 int getMaxIndex(); 122 123 /** 124 * Returns the path of this XML content value in the source document.<p> 125 * 126 * @return the path of this XML content value in the source document 127 */ 128 String getPath(); 129 130 /** 131 * Returns the value of this XML content node as a plain text String.<p> 132 * 133 * Plain text in this context means a pure textual representation 134 * of the content (i.e. without html tags). 135 * The plain text may be <code>null</code>, too, if there is no sound or useful 136 * textual representation (i.e. color values).<p> 137 * 138 * @param cms an initialized instance of a CmsObject 139 * 140 * @return the value of this XML content node as a plain text String 141 */ 142 String getPlainText(CmsObject cms); 143 144 /** 145 * Returns the search content type for the value. Default implementation uses the historic isSearchable() method. 146 * @return the search content type 147 */ 148 default SearchContentType getSearchContentType() { 149 150 return isSearchable() ? SearchContentType.TRUE : SearchContentType.FALSE; 151 } 152 153 /** 154 * Returns the value of this XML content node as a String.<p> 155 * 156 * @param cms an initialized instance of a CmsObject 157 * 158 * @return the value of this XML content node as a String 159 */ 160 String getStringValue(CmsObject cms); 161 162 /** 163 * Returns the node index of this XML content value in the source XML document, 164 * starting with 0, based on the XML ordering.<p> 165 * 166 * Elements in choice groups will be numbered like this: 167 * <code>Title[1], Text[1], Title[2], Image[1]</code><p> 168 * 169 * @return the index of this XML content node in the source document with special handling of elements in choice groups 170 * 171 * @see #getIndex() 172 */ 173 int getXmlIndex(); 174 175 /** 176 * Returns <code>true</code> in case this value is searchable by default with 177 * the integrated full text search.<p> 178 * 179 * @return <code>true</code> in case this value is searchable by default 180 */ 181 boolean isSearchable(); 182 183 /** 184 * Moves this XML content value one position down in the source document, if possible.<p> 185 * 186 * If the XML content value is already the first in it's sequence, it is not moved.<p> 187 */ 188 void moveDown(); 189 190 /** 191 * Moves this XML content value one position up in the source document, if possible.<p> 192 * 193 * If the XML content value is already the last in it's sequence, it is not moved.<p> 194 */ 195 void moveUp(); 196 197 /** 198 * Sets the provided String as value of this XML content node.<p> 199 * 200 * This method does provide processing of the content based on the 201 * users current OpenCms context. This can be used e.g. for link 202 * extraction and replacement in the content.<p> 203 * 204 * @param cms an initialized instance of a CmsObject 205 * @param value the value to set 206 * 207 */ 208 void setStringValue(CmsObject cms, String value); 209}