001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://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, please see the
018 * company website: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://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.search;
029
030import org.opencms.configuration.I_CmsConfigurationParameterHandler;
031import org.opencms.file.CmsObject;
032import org.opencms.file.CmsProperty;
033import org.opencms.file.CmsResource;
034import org.opencms.main.CmsIllegalArgumentException;
035import org.opencms.report.I_CmsReport;
036import org.opencms.search.documents.I_CmsDocumentFactory;
037import org.opencms.search.extractors.I_CmsExtractionResult;
038import org.opencms.search.fields.I_CmsSearchFieldConfiguration;
039
040import java.io.Serializable;
041import java.util.List;
042import java.util.Locale;
043
044/**
045 * Interface for search indizes that should be handled by the {@link org.opencms.search.CmsSearchManager}.
046 */
047public interface I_CmsSearchIndex extends I_CmsConfigurationParameterHandler, Serializable {
048
049    /** Automatic ("auto") index rebuild mode. */
050    static final String REBUILD_MODE_AUTO = "auto";
051
052    /** Manual ("manual") index rebuild mode. */
053    static final String REBUILD_MODE_MANUAL = "manual";
054
055    /** Offline ("offline") index rebuild mode. */
056    static final String REBUILD_MODE_OFFLINE = "offline";
057
058    /** Never ("never") index rebuild mode for indexes that should never be updated via OpenCms. */
059    static final String REBUILD_MODE_NEVER = "never";
060
061    /**
062     * The method should return the extraction result of a content from the index, if sure the
063     * content has not changed since last indexing. This will prevent re-extraction of the content.
064     * Preventing re-extraction saves time while indexing, e.g., if only meta-data of a content has changed.
065     * If no up-to-date content can be provided from the index, return <code>null</code>.
066     *
067     * @param resource the resource the content should be provided for.
068     * @return the up-to-date extraction result as gained from the index - if possible, or <code>null</code>,
069     *  if no up-to-date extraction result can be obtained from the index.
070     */
071    public I_CmsExtractionResult getContentIfUnchanged(CmsResource resource);
072
073    /**
074     * Returns the name of the field configuration used for this index.<p>
075     *
076     * @return the name of the field configuration used for this index
077     */
078    public String getFieldConfigurationName();
079
080    /**
081     * Returns the language locale for the given resource in this index.<p>
082     *
083     * @param cms the current OpenCms user context
084     * @param resource the resource to check
085     * @param availableLocales a list of locales supported by the resource
086     *
087     * @return the language locale for the given resource in this index
088     */
089    public Locale getLocaleForResource(CmsObject cms, CmsResource resource, List<Locale> availableLocales);
090
091    /**
092     * Returns all configured sources names of this search index.<p>
093     *
094     * @return a list with all configured sources names of this search index
095     */
096    public List<String> getSourceNames();
097
098    /**
099     * Returns <code>true</code> if full text is extracted by this index.<p>
100     *
101     * Full text content extraction can be turned off in the index search configuration parameters
102     * in <code>opencms-search.xml</code>.
103     * Not extraction the full text information will highly improve performance.<p>
104     *
105     * @return <code>true</code> if full text is extracted by this index
106     */
107    public boolean isExtractingContent();
108
109    /**
110     * Returns the languageDetection.<p>
111     *
112     * @return the languageDetection
113     */
114    public boolean isLanguageDetection();
115
116    /**
117     * Returns <code>true</code> in case this index is updated incremental.<p>
118     *
119     * An index is updated incremental if the index rebuild mode as defined by
120     * {@link #getRebuildMode()} is either set to {@value #REBUILD_MODE_AUTO} or
121     * {@value #REBUILD_MODE_OFFLINE}. Moreover, at least one update must have
122     * been written to the index already.
123     *
124     * @return <code>true</code> in case this index is updated incremental
125     */
126    public boolean isUpdatedIncremental();
127
128    /**
129     * Removes an index source from this search index.<p>
130     *
131     * @param sourceName the index source name to remove
132     */
133    public void removeSourceName(String sourceName);
134
135    /**
136     * Sets the locale to index resources.<p>
137     *
138     * @param locale the locale to index resources
139     */
140    public void setLocale(Locale locale);
141
142    /**
143     * Adds am index source to this search index.<p>
144     *
145     * @param sourceName the index source name to add
146     */
147    void addSourceName(String sourceName);
148
149    /**
150     * Indexes can provide index-specific document transformations
151     * Field configuration may use these to alter the generated document.
152     *
153     * @param document the document to transform
154     * @param cms the context
155     * @param resource the resource the document was created for
156     * @param extractionResult the extraction result for the resource
157     * @param properties the direct properties of the resource
158     * @param propertiesSearched the recursively read properties of the resource
159     * @return the transformed document
160     */
161    @SuppressWarnings("unused")
162    default I_CmsSearchDocument applyDocumentTransformation(
163        I_CmsSearchDocument document,
164        CmsObject cms,
165        CmsResource resource,
166        I_CmsExtractionResult extractionResult,
167        List<CmsProperty> properties,
168        List<CmsProperty> propertiesSearched) {
169
170        return document;
171    }
172
173    /**
174     * Checks is this index has been configured correctly.<p>
175     *
176     * In case the check fails, the <code>enabled</code> property
177     * is set to <code>false</code>
178     *
179     * @param cms a OpenCms user context to perform the checks with (should have "Administrator" permissions)
180     *
181     * @return <code>true</code> in case the index is correctly configured and enabled after the check
182     *
183     * @see #isEnabled()
184     */
185    boolean checkConfiguration(CmsObject cms);
186
187    /**
188     * Creates an empty document that can be used by this search field configuration.<p>
189     *
190     * @param resource the resource to create the document for
191     *
192     * @return a new and empty document
193     */
194    I_CmsSearchDocument createEmptyDocument(CmsResource resource);
195
196    /**
197     * Checks if the provided resource should be excluded from this search index.<p>
198     *
199     * @param cms the OpenCms context used for building the search index
200     * @param resource the resource to index
201     *
202     * @return true if the resource should be excluded, false if it should be included in this index
203     */
204    boolean excludeFromIndex(CmsObject cms, CmsResource resource);
205
206    /**
207     * Returns the document type factory used for the given resource in this index, or <code>null</code>
208     * in case the resource is not indexed by this index.<p>
209     *
210     * A resource is indexed if the following is all true: <ol>
211     * <li>The index contains at last one index source matching the root path of the given resource.
212     * <li>For this matching index source, the document type factory needed by the resource is also configured.
213     * </ol>
214     *
215     * @param res the resource to check
216     *
217     * @return he document type factory used for the given resource in this index, or <code>null</code>
218     * in case the resource is not indexed by this index
219     */
220    I_CmsDocumentFactory getDocumentFactory(CmsResource res);
221
222    /**
223     * Returns the search field configuration of this index.<p>
224     *
225     * @return the search field configuration of this index
226     */
227    I_CmsSearchFieldConfiguration getFieldConfiguration();
228
229    /**
230     * Returns a new index writer for this index.<p>
231     *
232     * @param report the report to write error messages on
233     * @param create if <code>true</code> a whole new index is created, if <code>false</code> an existing index is updated
234     *
235     * @return a new instance of IndexWriter
236     *
237     * @throws CmsIndexException if the index can not be opened
238     */
239    I_CmsIndexWriter getIndexWriter(I_CmsReport report, boolean create) throws CmsIndexException;
240
241    /**
242     * Returns the language locale of this index.<p>
243     *
244     * @return the language locale of this index, for example "en"
245     */
246    Locale getLocale();
247
248    /**
249     * Gets the name of this index.<p>
250     *
251     * @return the name of the index
252     */
253    String getName();
254
255    /**
256     * Returns the path where this index stores it's data in the "real" file system.<p>
257     *
258     * @return the path where this index stores it's data in the "real" file system
259     */
260    String getPath();
261
262    /**
263     * Gets the project of this index.<p>
264     *
265     * @return the project of the index, i.e. "online"
266     */
267    String getProject();
268
269    /**
270     * Get the rebuild mode of this index.<p>
271     *
272     * @return the current rebuild mode
273     */
274    String getRebuildMode();
275
276    /**
277     * Returns all configured index sources of this search index.<p>
278     *
279     * @return all configured index sources of this search index
280     */
281    List<CmsSearchIndexSource> getSources();
282
283    /**
284     * Initializes the search index.<p>
285     *
286     * @throws CmsSearchException if the index source association failed or a configuration error occurred
287     */
288
289    void initialize() throws CmsSearchException;
290
291    /**
292     * Returns <code>true</code> if this index is currently disabled.<p>
293     *
294     * @return <code>true</code> if this index is currently disabled
295     */
296    boolean isEnabled();
297
298    /**
299     * Returns a flag, indicating if the search index is successfully initialized.
300     * @return a flag, indicating if the search index is successfully initialized.
301     */
302    boolean isInitialized();
303
304    /**
305     * Method called by the search manager if the index has changed.
306     * Typically the index searcher is reset when the method is called.
307     *
308     * @param force if <code>false</code> the index might decide itself it it has to act on the change,
309     *  if <code>true</code> it should act, even if itself cannot detect an index change.
310     */
311    void onIndexChanged(boolean force);
312
313    /**
314     * Can be used to enable / disable this index.<p>
315     *
316     * @param enabled the state of the index to set
317     */
318    void setEnabled(boolean enabled);
319
320    /**
321     * Sets the name of the field configuration used for this index.<p>
322     *
323     * @param fieldConfigurationName the name of the field configuration to set
324     */
325    void setFieldConfigurationName(String fieldConfigurationName);
326
327    /**
328     * Sets the locale to index resources as a String.<p>
329     *
330     * @param locale the locale to index resources
331     *
332     * @see #setLocale(Locale)
333     */
334    void setLocaleString(String locale);
335
336    /**
337     * Sets the logical key/name of this search index.<p>
338     *
339     * @param name the logical key/name of this search index
340     *
341     * @throws CmsIllegalArgumentException if the given name is null, empty or already taken by another search index
342     */
343    void setName(String name) throws CmsIllegalArgumentException;
344
345    /**
346     * Sets the name of the project used to index resources.<p>
347     *
348     * @param project the name of the project used to index resources
349     */
350    void setProject(String project);
351
352    /**
353     * Sets the rebuild mode of this search index.<p>
354     *
355     * @param rebuildMode the rebuild mode of this search index {auto|manual}
356     */
357    void setRebuildMode(String rebuildMode);
358
359    /**
360     * Shuts down the search index.<p>
361     *
362     * This will close the local Lucene index searcher instance.<p>
363     */
364    void shutDown();
365}