org.eclipse.jdt.core.search.SearchDocument Maven / Gradle / Ivy

/*******************************************************************************
 * Copyright (c) 2000, 2014 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core.search;

import org.eclipse.jdt.internal.compiler.SourceElementParser;
import org.eclipse.jdt.internal.core.index.Index;

/**
 * A search document encapsulates a content to be either indexed or searched in.
 * A search participant creates a search document.
 * 
 * This class is intended to be subclassed by clients.
 * 
 *
 * @since 3.0
 */
public abstract class SearchDocument {
	private Index index;
	private String containerRelativePath;
	private SourceElementParser parser;
	private String documentPath;
	private SearchParticipant participant;
	private boolean shouldIndexResolvedDocument = false;

	/**
	 * Creates a new search document. The given document path is a string that uniquely identifies the document.
	 * Most of the time it is a workspace-relative path, but it can also be a file system path, or a path inside a zip file.
	 *
	 * @param documentPath the path to the document,
	 * or null if none
	 * @param participant the participant that creates the search document
	 */
	protected SearchDocument(String documentPath, SearchParticipant participant) {
		this.documentPath = documentPath;
		this.participant = participant;
	}

	/**
	 * Adds the given index entry (category and key) coming from this
	 * document to the index. This method must be called from
	 * {@link SearchParticipant#indexDocument(SearchDocument document, org.eclipse.core.runtime.IPath indexPath)}.
	 *
	 * @param category the category of the index entry
	 * @param key the key of the index entry
	 */
	public void addIndexEntry(char[] category, char[] key) {
		if (this.index != null)
			this.index.addIndexEntry(category, key, getContainerRelativePath());
	}

	/**
	 * Returns the contents of this document.
	 * Contents may be different from actual resource at corresponding document path,
	 * in case of preprocessing.
	 * 
	 * This method must be implemented in subclasses.
	 * 

	 * Note: some implementation may choose to cache the contents directly on the
	 * document for performance reason. However, this could induce scalability issues due
	 * to the fact that collections of documents are manipulated throughout the search
	 * operation, and cached contents would then consume lots of memory until they are
	 * all released at once in the end.
	 * 
	 *
	 * @return the contents of this document,
	 * or null if none
	 */
	public abstract byte[] getByteContents();

	/**
	 * Returns the contents of this document.
	 * Contents may be different from actual resource at corresponding document
	 * path due to preprocessing.
	 * 
	 * This method must be implemented in subclasses.
	 * 

	 * Note: some implementation may choose to cache the contents directly on the
	 * document for performance reason. However, this could induce scalability issues due
	 * to the fact that collections of documents are manipulated throughout the search
	 * operation, and cached contents would then consume lots of memory until they are
	 * all released at once in the end.
	 * 
	 *
	 * @return the contents of this document,
	 * or null if none
	 */
	public abstract char[] getCharContents();

	private String getContainerRelativePath() {
		if (this.containerRelativePath == null)
			this.containerRelativePath = this.index.containerRelativePath(getPath());
		return this.containerRelativePath;
	}

	/**
	 * Returns the encoding for this document.
	 * 
	 * This method must be implemented in subclasses.
	 * 
	 *
	 * @return the encoding for this document,
	 * or null if none
	 */
	public abstract String getEncoding();

	/**
	 * @nooverride This method is not intended to be re-implemented or extended by clients.
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public SourceElementParser getParser() {
		return this.parser;
	}
	
	/**
	 * Returns the participant that created this document.
	 *
	 * @return the participant that created this document
	 */
	public final SearchParticipant getParticipant() {
		return this.participant;
	}

	/**
	 * Returns the path to the original document to publicly mention in index
	 * or search results. This path is a string that uniquely identifies the document.
	 * Most of the time it is a workspace-relative path, but it can also be a file system path,
	 * or a path inside a zip file.
	 *
	 * @return the path to the document
	 */
	public final String getPath() {
		return this.documentPath;
	}
	/**
	 * Removes all index entries from the index for the given document.
	 * This method must be called from
	 * {@link SearchParticipant#indexDocument(SearchDocument document, org.eclipse.core.runtime.IPath indexPath)}.
	 */
	public void removeAllIndexEntries() {
		if (this.index != null)
			this.index.remove(getContainerRelativePath());
	}
	
	/**
	 * @nooverride This method is not intended to be re-implemented or extended by clients.
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public void setIndex(Index indexToSet) {
		this.index = indexToSet;
	}
	
	/**
	 * @nooverride This method is not intended to be re-implemented or extended by clients.
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public void setParser(SourceElementParser sourceElementParser) {
		this.parser = sourceElementParser;
	}

	/** Flags the document as requiring indexing after symbol and type resolution. A participant would be asked 
	 *  to resolve the document via {@link SearchParticipant#resolveDocument} and to index the document adding 
	 *  additional entries via {@link SearchParticipant#indexResolvedDocument} 
	 *  
	 * @since 3.10 
	 */
	public void requireIndexingResolvedDocument() {
		this.shouldIndexResolvedDocument = true;
	}
	
	/**
	 * @nooverride This method is not intended to be re-implemented or extended by clients.
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public boolean shouldIndexResolvedDocument() {
		return this.shouldIndexResolvedDocument;
	}
}