Package oracle.ide.file

Classes and interfaces used to track changes to files.

See: Description

Interface Summary

Interface	Description
FileChange	A change to a file.
FileChangeListener	Listens for changes to files in a FileScope.
FileScope	A scope in which files are monitored.
FileSetFilter	Filters the files in a FileSet.
FileTableRemovedListener	Listens for removal of FileTable.
FileTableVisitor

Class Summary

Class	Description
AbstractFileScope	Base class for file scope implementations.
ContentSetKey	A key used to look up cached information about a content set.
ContentSetRoot	A single root directory in a ContentSet.
ContentSetScope	File scope that includes the files in a project ContentSet.
FileChanges	A collection of changes to files.
FileSet	A set of files selected from a single root directory.
FileSetFilters	Provides common implementations of FileSetFilter.
FileSetTable	Abstract base class for file table implementations based on FileSet.
FileTable	Persistently stores information about a set of files, and provides a mapping from each file to an integer ID.
LibraryPaths	The source and class paths of a library.
Path	An ordered path made up of FileSet.
ProjectCache	Caches project properties.
ProjectCache.CacheEntry<E>

Enum Summary

Enum	Description
FileChange.Type	The type of change.
FileTableVisitor.Result

Exception Summary

Exception	Description
FileChangesExpiredException	Thrown when file change data has expired.
InvalidFileTableException	Thrown if the file table data is determined to be invalid.

Package oracle.ide.file Description

Classes and interfaces used to track changes to files.

There are two ways to receive notification about file changes:

• Active listener: the listener is notified of file change events as they happen. Active listeners use the addFileChangeListener method.
• On-demand listener: the caller asks for the file changes since a previous point in time. On-demand listeners use the getChangesSince method.

In almost all cases, the use of on-demand listening is preferred. Use of active listeners is strongly discouraged. Active listeners can cause performance problems, because the listener is executed every time a file changes. Active listeners are also called asynchronously - that is, the event may not be received immediately when a file change occurs, but at some later time. This means that active listeners cannot be used for anything which requires synchronous notification of changes. For example, if you use the file change events to invalidate a cache, it would be possible for a client of that cache to see stale cache data that did not include recent changes. Active listeners are only suitable in rare cases where synchronous event delivery is not required, and when the listener code is very fast. For example, a UI showing search results could use an active listener to display notification to the user that the results are no longer valid and need to be refreshed.

With on-demand listening, the listener is instead called only when the client needs to be updated. At that point, it can synchronously obtain all changes since a previous point in time. For example, a cache might contain cached data which is invalid once a file changes. When a client calls into the cache, it can query the file change API to obtain all the file changes since the last time the cache was updated. This will include all changes up to the point where the call is made. This mechanism ensures that the cache is always up to date with the latest changes. It also avoids performance problems. Rather than updating the cache immediately every time a file changes, the cache is updated only when a client uses it. This avoids wasting time continuously updating caches that no one is using.

A typical pattern for using on-demand listening to invalidate a cache is as follows:

1. Call getFileTables to get the file tables for the scope you are interested in. Do not cache this list of tables, as it can change. Call this each time to get the current list.
2. For each file table:
   1. Call getChangesSince. If you've never seen this file table before, use FIRST_VERSION for the version and -1L for the cookie. Otherwise, pass in the version and cookie from the last time.
   2. If you get a FileChangesExpiredException, clear all your cache data for that file table, then call getChangesSince again, this time passing FIRST_VERSION and -1L.
   3. Process any events received and use them to update your cache. Store the new cookie and version of the file table along with the cache data.
3. Your cache is now to be up to date, and you can returned your cached data.

Since:

11.1.2