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