org.modeshape.jcr.api.index.IndexManager Maven / Gradle / Ivy
/*
* ModeShape (http://www.modeshape.org)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.modeshape.jcr.api.index;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.jcr.RepositoryException;
import javax.jcr.Workspace;
import javax.jcr.nodetype.NodeTypeManager;
/**
* An interface for programmatically adding or removing index providers and index definitions. Even though this is accessed via
* {@link org.modeshape.jcr.api.Workspace#getIndexManager}, like {@link NodeTypeManager} it represents a session's mechanism to
* define, alter, or remove index definitions for the whole repository (not just the session's {@link Workspace#getName()
* workspace}).
*
* To create an IndexDefinition:
*
* - Call the {@link #createIndexDefinitionTemplate()} method to obtain a new blank template
* - Call the setter methods on the {@link IndexDefinitionTemplate} to make the template accurately describe the new or updated
* index definition
* - For each of the index definition's columns, {@link #createIndexColumnDefinitionTemplate() create a column definition
* template} and call the setters to define the {@link IndexColumnDefinitionTemplate#setPropertyName(String) property name} to
* which the column applies and the {@link IndexColumnDefinitionTemplate#setColumnType(int) type for the column}.
* - Call the {@link IndexDefinitionTemplate#setColumnDefinitions(Iterable)} to assign the column definitions to the index
* definition
*
* The resulting {@link IndexDefinitionTemplate}, which is also an {@link IndexDefinition}, can then be passed to the
* {@link #registerIndex(IndexDefinition, boolean)} or {@link #registerIndexes(IndexDefinition[], boolean)} methods to add/update
* the index definition.
*
* @author Randall Hauch ([email protected])
* @see org.modeshape.jcr.api.Workspace#getIndexManager()
*/
public interface IndexManager {
/**
* Get the names of the available index providers.
*
* @return the immutable set of provider names; never null but possibly empty
*/
Set getProviderNames();
/**
* Get a map of the registered index definitions keyed by their names. The resulting map is immutable, but it is updated
* whenever an index definition is added, updated, or removed. To add an index, use
* {@link #registerIndex(IndexDefinition, boolean)} or {@link #registerIndexes(IndexDefinition[], boolean)}; to remove an
* index, use {@link #unregisterIndexes}.
*
* @return the index definitions; never null but possibly empty
*/
Map getIndexDefinitions();
/**
* Register a new definition for an index.
*
* @param indexDefinition the definition; may not be null
* @param allowUpdate true if the definition can update or overwrite an existing definition with the same name, or false if
* calling this method should result in an exception when the repository already contains a definition with the same
* name already exists
* @throws InvalidIndexDefinitionException if the new definition is invalid
* @throws IndexExistsException if allowUpdate is false and the IndexDefinition
* specifies a node type name that is already registered.
* @throws RepositoryException if there is a problem registering the new definition, or if an existing index
*/
void registerIndex( IndexDefinition indexDefinition,
boolean allowUpdate ) throws InvalidIndexDefinitionException, IndexExistsException, RepositoryException;
/**
* Register new definitions for several indexes.
*
* @param indexDefinitions the definitions; may not be null
* @param allowUpdate true if each of the definition can update or overwrite an existing definition with the same name, or
* false if calling this method should result in an exception when the repository already contains any definition with
* names that match the supplied definitions
* @throws InvalidIndexDefinitionException if the new definition is invalid
* @throws IndexExistsException if allowUpdate is false and the IndexDefinition
* specifies a node type name that is already registered.
* @throws RepositoryException if there is a problem registering the new definition, or if an existing index
*/
void registerIndexes( IndexDefinition[] indexDefinitions,
boolean allowUpdate ) throws InvalidIndexDefinitionException, IndexExistsException, RepositoryException;
/**
* Removes an existing index definition.
*
* @param indexNames the names of the index definition to be removed; may not be null
* @throws NoSuchIndexException there is no index with the supplied name
* @throws RepositoryException if there is a problem registering the new definition, or if an existing index
*/
void unregisterIndexes( String... indexNames ) throws NoSuchIndexException, RepositoryException;
/**
* Create a new template that can be used to programmatically define an index.
*
* @return the new template; may not be null
*/
IndexDefinitionTemplate createIndexDefinitionTemplate();
/**
* Create a new template that can be used to programmatically define a column on an index.
*
* @return the new template; may not be null
*/
IndexColumnDefinitionTemplate createIndexColumnDefinitionTemplate();
/**
* Returns the status of the index with the given name for the given provider and workspace.
*
* @param providerName a {@link String} the name of an index provider; may not be null
* @param indexName a {@link String} the name of an index which should exist for the provider; may not be null
* @param workspaceName a {@link String} the name of a workspace for which the index was created; may not be null
* @return a {@link org.modeshape.jcr.api.index.IndexManager.IndexStatus} instance, never {@code null} but possibly
* {@link org.modeshape.jcr.api.index.IndexManager.IndexStatus#NON_EXISTENT} if a provider with this name does not exist
* or an index with this name does not exist for the provider or the index doesn't exist for the given workspace.
*/
IndexStatus getIndexStatus( String providerName, String indexName, String workspaceName );
/**
* Returns a list with the names of all the indexes that have a certain status, for a provider and workspace.
*
* @param providerName a {@link String} the name of an index provider; may not be null
* @param workspaceName a {@link String} the name of a workspace for which the index was created; may not be null
* @param status a {@link org.modeshape.jcr.api.index.IndexManager.IndexStatus} instance; may not be null
* @return a List with the names of all the indexes belonging to the provider which have the given status and apply to the workspace;
* never {@code null}
*/
List getIndexNames(String providerName, String workspaceName, IndexStatus status);
/**
* Enum with a list of possible statuses for managed indexes.
*/
enum IndexStatus {
/**
* Active index being considered/used by the query engine when executing queries
*/
ENABLED,
/**
* Active index which is re-indexing its data but is not being used by the query engine
*/
REINDEXING,
/**
* Inactive index which has been disabled or shut down.
*/
DISABLED,
/**
* Index which does not exist
*/
NON_EXISTENT
}
}