001/*
002 * File   : $Source$
003 * Date   : $Date$
004 * Version: $Revision$
005 *
006 * This library is part of OpenCms -
007 * the Open Source Content Management System
008 *
009 * Copyright (C) 2002 - 2009 Alkacon Software (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, 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
032package org.opencms.search.fields;
033
034import org.opencms.file.CmsObject;
035import org.opencms.file.CmsProperty;
036import org.opencms.file.CmsResource;
037import org.opencms.search.extractors.I_CmsExtractionResult;
038
039import java.io.Serializable;
040import java.util.List;
041import java.util.Locale;
042
043/**
044 * Describes a mapping of a piece of content from an OpenCms VFS
045 * resource to a field of a search index.<p>
046 *
047 * @since 8.5.0
048 */
049public interface I_CmsSearchFieldMapping extends Serializable {
050
051    /**
052     * Returns the default value used for this field mapping in case no content is available.<p>
053     *
054     * @return the default value used for this field mapping in case no content is available
055     */
056    String getDefaultValue();
057
058    /**
059     * Returns the mapping parameter.<p>
060     *
061     * The parameter is used depending on the implementation of the rules of
062     * the selected {@link CmsSearchFieldMappingType}.<p>
063     *
064     * @return the mapping parameter
065     */
066    String getParam();
067
068    /**
069     * Returns the String value extracted form the provided data according to the rules of this mapping type.<p>
070     *
071     * @param cms the OpenCms context used for building the search index
072     * @param res the resource that is indexed
073     * @param extractionResult the plain text extraction result from the resource
074     * @param properties the list of all properties directly attached to the resource (not searched)
075     * @param propertiesSearched the list of all searched properties of the resource
076     *
077     * @return the String value extracted form the provided data according to the rules of this mapping type
078     */
079    String getStringValue(
080        CmsObject cms,
081        CmsResource res,
082        I_CmsExtractionResult extractionResult,
083        List<CmsProperty> properties,
084        List<CmsProperty> propertiesSearched);
085
086    /**
087     * Returns the mapping type.<p>
088     *
089     * @return the mapping type
090     */
091    CmsSearchFieldMappingType getType();
092
093    /**
094     * Sets the default value for this field mapping in case no content is available.<p>
095     *
096     * @param defaultValue the default value to set
097     */
098    void setDefaultValue(String defaultValue);
099
100    /**
101     * Sets the locale, the mapping can examine when extracting the content.
102     *
103     * NOTE: This method is called by {@link org.opencms.xml.content.CmsDefaultXmlContentHandler}
104     *  when dynamic search field mappings are created.
105     *  Overwrite this default implementation if you need to map locale specific in your dynamic mapping.
106     *
107     * @param locale the locale of the index field that is filled by the mapping.
108     */
109    default void setLocale(Locale locale) {
110
111        return;
112    }
113
114    /**
115     * Sets the mapping parameter.<p>
116     *
117     * The parameter is used depending on the implementation of the rules of
118     * the selected {@link CmsSearchFieldMappingType}.<p>
119     *
120     * @param param the parameter to set
121     */
122    void setParam(String param);
123
124    /**
125     * Sets the mapping type.<p>
126     *
127     * @param type the type to set
128     */
129    void setType(CmsSearchFieldMappingType type);
130
131    /**
132     * Sets the mapping type as a String.<p>
133     *
134     * @param type the name of the type to set
135     */
136    void setType(String type);
137}