oracle.ide.index
Interface Index

public interface Index

Field Summary

static java.net.URL	END_OF_RESULTS Marker used to indicate the last result of an index query.
static int	FLAGS_NONE Value indicating that no flags are set.
static QueryResult	LAST_RESULT Marker used to indicate the last result of an index query.

Method Summary

void	blockingBuild() Builds the index on the calling thread.
java.net.URL[]	blockingQuery(QueryCriteria criteria) Query the index on the calling thread.
java.util.Collection<QueryResult>	blockingQueryEx(QueryCriteria criteria) Query the index on the calling thread.
BackgroundTask	build() Request that the index be built in a background task.
QueryProgress	findNodes(java.lang.Class nodeClass, ResultCallback<Node> callback) Convenience method to find all Nodes of the given type in the scope of this index.
QueryProgress	findNodes(QueryCriteria criteria, java.lang.Class nodeClass, ResultCallback<Node> callback) Convenience method to find all Nodes of the given type in the scope of this index, that also match the given crieria.
int[][]	locate(java.net.URL url, java.lang.Object key, java.lang.Object value) Locate the matches for the given data in the given file.
void	lock() Locks the index.
BackgroundTask<java.net.URL[]>	query(QueryCriteria criteria) Query the index in a background task.
BackgroundTask<java.net.URL[]>	query(QueryCriteria criteria, java.util.concurrent.BlockingQueue<java.net.URL> queue) Query the index in a background task.
QueryProgress	query(QueryCriteria criteria, ResultCallback<java.net.URL> callback) Query the index in a background task.
BackgroundTask<java.util.Collection<QueryResult>>	queryEx(QueryCriteria criteria) Query the index in a background task.
BackgroundTask<java.util.Collection<QueryResult>>	queryEx(QueryCriteria criteria, java.util.concurrent.BlockingQueue<QueryResult> queue) Query the index in a background task.
QueryProgress	queryEx(QueryCriteria criteria, ResultCallback<QueryResult> callback) Query the index in a background task.
void	release() Release this index when it is no longer needed.
void	unlock() Unlocks the index.

Field Detail

END_OF_RESULTS

static final java.net.URL END_OF_RESULTS

Marker used to indicate the last result of an index query.

LAST_RESULT

static final QueryResult LAST_RESULT

Marker used to indicate the last result of an index query.

FLAGS_NONE

static final int FLAGS_NONE

Value indicating that no flags are set.

See Also:

locate(java.net.URL, java.lang.Object, java.lang.Object), Constant Field Values

Method Detail

lock

void lock()
          throws java.lang.InterruptedException,
                 LockFailedException

Locks the index. Locking the index is required when running blocking queries. Once the index is locked, multiple blocking queries can be run before unlocking. The index will be updated at most one time while it is locked. This ensures that the results of the queries are consistent, and improves performance over locking the index seaprately for each query (in which case, the index could be updated before each query).

Note that locking the index does not prevent other callers from locking or querying the index. It only prevents the index data from being updated more than once while there is at least one call to lock() that has not been matched by a corresponding call to unlock().

Callers should take care to ensure that each call to lock() is followed by a corresponding call to unlock(). Typically this is done by following each call to lock() with a try-finally block whose finally clause unlocks the index. Note that the lock operation is interruptible.

Throws:

java.lang.InterruptedException - if the lock operation is interrupted

LockFailedException - if the lock failed

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

unlock

void unlock()

Unlocks the index.

build

BackgroundTask build()

Request that the index be built in a background task. Note that if the caller holds a write lock on the text buffer of a Node at the time of the build, blockingBuild() must be used instead to prevent deadlock between the calling thread an the index thread.

Returns:

the background task that will build the index

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

blockingBuild

void blockingBuild()
                   throws java.lang.InterruptedException

Builds the index on the calling thread. The index must be locked before calling this method. This method may take a long time to execute if the index is not up to date. Callers should take steps to avoid blocking the UI thread when calling this method.

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

java.lang.InterruptedException

blockingQuery

java.net.URL[] blockingQuery(QueryCriteria criteria)
                             throws java.lang.InterruptedException,
                                    QueryFailedException

Query the index on the calling thread. The index must be locked before calling this method. This method may take a long time to execute, for example if the index has not been built yet. Callers should take steps to avoid blocking the UI thread when calling this method.

Parameters:

criteria - the query criteria

Returns:

the URLs matching the criteria

Throws:

java.lang.InterruptedException - if the query is interrupted

QueryFailedException - if the query failed

blockingQueryEx

java.util.Collection<QueryResult> blockingQueryEx(QueryCriteria criteria)
                                                  throws java.lang.InterruptedException,
                                                         QueryFailedException

Query the index on the calling thread. The index must be locked before calling this method. This method may take a long time to execute, for example if the index has not been built yet. Callers should take steps to avoid blocking the UI thread when calling this method.

Parameters:

criteria - the query criteria

Returns:

the results matching the criteria

Throws:

java.lang.InterruptedException - if the query is interrupted

QueryFailedException - if the query failed

query

BackgroundTask<java.net.URL[]> query(QueryCriteria criteria)

Query the index in a background task.

Parameters:

criteria - the query criteria

Returns:

the background task that will run the query

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

queryEx

BackgroundTask<java.util.Collection<QueryResult>> queryEx(QueryCriteria criteria)

Query the index in a background task.

Parameters:

criteria - the query criteria

Returns:

the background task that will run the query

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

query

BackgroundTask<java.net.URL[]> query(QueryCriteria criteria,
                                     java.util.concurrent.BlockingQueue<java.net.URL> queue)

Query the index in a background task. Callers can supply a queue to receive results as they are found.

Parameters:

criteria - the query critieria

queue - the result queue

Returns:

the background task that will run the query

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

queryEx

BackgroundTask<java.util.Collection<QueryResult>> queryEx(QueryCriteria criteria,
                                                          java.util.concurrent.BlockingQueue<QueryResult> queue)

Query the index in a background task. Callers can supply a queue to receive results as they are found.

Parameters:

criteria - the query critieria

queue - the result queue

Returns:

the background task that will run the query

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

query

QueryProgress query(QueryCriteria criteria,
                    ResultCallback<java.net.URL> callback)

Query the index in a background task. The caller provides a callback which will be called with the results of the query.

Parameters:

criteria - the query criteria

callback - the callback to call with results

Returns:

a progress monitor which can be used to track the query progress

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

queryEx

QueryProgress queryEx(QueryCriteria criteria,
                      ResultCallback<QueryResult> callback)

Query the index in a background task. The caller provides a callback which will be called with the results of the query.

Parameters:

criteria - the query criteria

callback - the callback to call with results

Returns:

a progress monitor which can be used to track the query progress

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

locate

int[][] locate(java.net.URL url,
               java.lang.Object key,
               java.lang.Object value)

Locate the matches for the given data in the given file. This is typically used to locate the matches in a file returned as a query result. If the specified file does not contain any matches for this data, an empty array is returned. Note that it is possible for a query to return a URL as a match, but for locate() to return an empty array. This can happen, for example, if the file contents have changed since the index was generated. Also, note that some criteria do not correspond to a location within the file, for example, FILE_EXTENSION. This method will return empty results for such criteria.

This method is for legacy code. It is strongly recommended that new code use the extended query methods to query the location data stored in the index.

Parameters:

url - the URL of the file

key - the data key

value - the data value to locate

Returns:

an array of 3 integer arrays, one for start position, end position, and flags

findNodes

QueryProgress findNodes(java.lang.Class nodeClass,
                        ResultCallback<Node> callback)

Convenience method to find all Nodes of the given type in the scope of this index. This takes advantage of the index data to locate the Nodes, so the performance will typically be much better than Project.findChildren(Class).

This method will look at every file in the index, and check if it matches the given Node type. In a large project, this can take some time. If possible, you can increase performance by supplying additional index query criteria using the findNodes(QueryCriteria,Class,ResultCallback) version of this method.

Parameters:

nodeClass - the node class to find

callback - the callback to call with results

Returns:

a progress monitor which can be used to track the query progress

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

findNodes

QueryProgress findNodes(QueryCriteria criteria,
                        java.lang.Class nodeClass,
                        ResultCallback<Node> callback)

Convenience method to find all Nodes of the given type in the scope of this index, that also match the given crieria. This takes advantage of the index data to locate the Nodes, so the performance will typically be much better than Project.findChildren(Class).

This method will only look at the Node type of files that match the given index query critiera. This improves performance over the findNodes(Class,ResultCallback) version of this method, which must check the Node type of every file in the index. For example, if you use FILE_EXTENSION, only files that have the given file extension will be checked.

Parameters:

criteria - the index query criteria

nodeClass - the node class to find

callback - the callback to call with results

Returns:

a progress monitor which can be used to track the query progress

Throws:

java.util.concurrent.RejectedExecutionException - if the indexing service has been shut down

release

void release()

Release this index when it is no longer needed. This ensures that all file system resources used by this index can be released when the index is no longer in use.