Skip navigation links

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.3.0)

E17493-04


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.

Skip navigation links

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.3.0)

E17493-04


Copyright © 1997, 2012, Oracle. All rights reserved.