oracle.ide.file
Class FileTable

java.lang.Object
  oracle.ide.file.FileTable

All Implemented Interfaces:

FileScope

Direct Known Subclasses:

FileSetTable

public abstract class FileTable
extends java.lang.Object
implements FileScope

Persistently stores information about a set of files, and provides a mapping from each file to an integer ID.

Since:

11.1.2

Nested Class Summary

protected class

FileTable.FileChangeImpl Implementation of the FileChange interface.

Field Summary

static int	FIRST_VERSION The first version of a file table.
static int	INVALID_FILE_ID Constant used to mark an invalid file ID.
protected static boolean	IS_KAVA_TEST Whether we are running in the Kava tests.
protected java.util.List<FileChangeListener>	listeners The listeners for this file table.
protected static java.util.logging.Logger	LOGGER The logger for file table messages.
static int	REMOVED_VERSION Version constant used to deliver removed events for all files in the file table.
protected Storage	storage The storage this file table is stored in.

Constructor Summary

protected

FileTable(Storage storage)

Method Summary

void	activate() Activate this file table.
protected void	activateImpl() Called when a file table is activated.
void	addFileChangeListener(FileChangeListener listener) Add a file change listener to receive events about the files in this scope.
abstract void	adjustTimestamps() Adjust the timestamps stored in this file table.
void	deactivate() Deactivate this file table.
protected void	deactivateImpl() Called when a file is deactivated.
abstract void	delete() Delete the file table from storage.
abstract void	getChangesSince(int version, long cookie, FileChangeListener listener) Get the changes since an older version of the file data.
FileTable	getFileTable(java.net.URL url) Get the file table in this scope containing a particular URL.
java.util.Collection<FileTable>	getFileTables() Get the file tables currently used by this scope.
abstract int	getId(java.net.URL url) Get the ID of a file in this table.
abstract long	getLastModified(int id) Get the last modified time of a file in this file table.
abstract long	getLength(int id) Get the length of a file in this file table.
protected static boolean	getRefreshAutomatically() Determine whether file tables should be refreshed automatically when there are external changes.
protected static boolean	getRefreshOnStartup() Determine whether file tables should be refreshed the first time they are used in an IDE session.
abstract java.lang.String	getRelativePath(java.net.URL url) Get the path of a URL relative to the root of this file table.
Storage	getStorage() Get underlying storage used to store the file data.
abstract java.lang.String	getStorageKey() Get a unique identifier for this file table.
abstract java.net.URL	getURL(int id) Get the URL for a file ID in this file table.
abstract void	invalidate() Invalidates the file table.
static void	invalidateAllJars() Invalidate all file tables that have data for JAR files.
static void	invalidateDirectory(java.net.URL directory, boolean includeSubdirectories) Invalidate all active file tables that have data for a directory.
static void	invalidateDirectory(java.net.URL directory, java.net.URL renameHintOldURL, java.net.URL renameHintNewURL) Invalidate all active file tables that have data for a directory, due to a file being renamed.
protected abstract void	invalidateDirectoryImpl(java.net.URL directory, boolean includeSubdirectories, java.net.URL renameHintOldURL, java.net.URL renameHintNewURL) Invalidates a directory in this file table.
static void	invalidateFile(java.net.URL file, boolean isBufferChange) Invalidate all active file tables that have data for a specific file.
protected abstract void	invalidateFileImpl(java.net.URL file, boolean isBufferChange) Invalidates a file in this file table.
static void	invalidateJar(java.net.URL jar) Invalidate all active file tables that have data for a specific JAR file.
protected void	invokeListener(FileChangeListener listener, FileChanges changes) Invoke a specific listener with a set of changes.
protected void	invokeListeners(FileChanges changes) Invoke the listeners on this file table with a set of changes.
void	refresh() Refresh this scope.
protected abstract void	refreshDirectory(java.net.URL directory, boolean includeSubdirectories, java.net.URL renameHintOldURL, java.net.URL renameHintNewURL) Synchronously refresh the file table data for a specific directory.
protected abstract void	refreshFile(java.net.URL file, boolean isBufferChange) Synchronously refresh the file table data for a specific file.
void	removeFileChangeListener(FileChangeListener listener) Remove a file change listener from this scope.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.ide.file.FileScope

contains, getDirectories, getFiles, locate, refresh, update

Field Detail

FIRST_VERSION

public static final int FIRST_VERSION

The first version of a file table.

See Also:

getChangesSince(int, long, oracle.ide.file.FileChangeListener), Constant Field Values

REMOVED_VERSION

public static final int REMOVED_VERSION

Version constant used to deliver removed events for all files in the file table. This is used when a file table has been removed from a scope.

See Also:

getChangesSince(int, long, oracle.ide.file.FileChangeListener), Constant Field Values

INVALID_FILE_ID

public static final int INVALID_FILE_ID

Constant used to mark an invalid file ID.

See Also:

Constant Field Values

LOGGER

protected static final java.util.logging.Logger LOGGER

The logger for file table messages.

IS_KAVA_TEST

protected static final boolean IS_KAVA_TEST

Whether we are running in the Kava tests.

storage

protected final Storage storage

The storage this file table is stored in.

listeners

protected final java.util.List<FileChangeListener> listeners

The listeners for this file table.

Constructor Detail

FileTable

protected FileTable(Storage storage)

Method Detail

invalidateDirectory

public static void invalidateDirectory(@NotNull
                                       java.net.URL directory,
                                       boolean includeSubdirectories)

Invalidate all active file tables that have data for a directory. Optionally invalidates all subdirectories, recursively. This should be called when there are known to be changes within a directory.

Parameters:

directory - the directory to invalidate

includeSubdirectories - whether to also invalidate subdirectories

invalidateDirectory

public static void invalidateDirectory(@NotNull
                                       java.net.URL directory,
                                       @NotNull
                                       java.net.URL renameHintOldURL,
                                       @NotNull
                                       java.net.URL renameHintNewURL)

Invalidate all active file tables that have data for a directory, due to a file being renamed.

Parameters:

directory - the directory to invalidate

renameHintOldURL - the new location of the file if the directory invalidation is due to a file being renamed

renameHintNewURL - the old location of the file if the directory invalidation is due to a file being renamed

invalidateFile

public static void invalidateFile(@NotNull
                                  java.net.URL file,
                                  boolean isBufferChange)

Invalidate all active file tables that have data for a specific file. This should be called when a file's contents have been modified. This does not invalidate the containing directory. If the file has been added, removed, or renamed, the directory should be invalidated instead.

Parameters:

file - the file being invalidated

isBufferChange - true if the changes are only in memory and not saved to disk, false otherwise

invalidateJar

public static void invalidateJar(@NotNull
                                 java.net.URL jar)

Invalidate all active file tables that have data for a specific JAR file.

Parameters:

jar - the JAR file being invalidated

invalidateAllJars

public static void invalidateAllJars()

Invalidate all file tables that have data for JAR files.

getRefreshAutomatically

protected static boolean getRefreshAutomatically()

Determine whether file tables should be refreshed automatically when there are external changes.

Returns:

true if file tables should be refreshed automatically, false otherwise

getRefreshOnStartup

protected static boolean getRefreshOnStartup()

Determine whether file tables should be refreshed the first time they are used in an IDE session.

Returns:

true if file tables should be refreshed the first time they are used in an IDE session, false otherwise

addFileChangeListener

public void addFileChangeListener(FileChangeListener listener)

Description copied from interface: FileScope

Add a file change listener to receive events about the files in this scope.

Specified by:

addFileChangeListener in interface FileScope

Parameters:

listener - the listener to be added

removeFileChangeListener

public void removeFileChangeListener(FileChangeListener listener)

Description copied from interface: FileScope

Remove a file change listener from this scope.

Specified by:

removeFileChangeListener in interface FileScope

Parameters:

listener - the listener to be removed

activate

public void activate()

Activate this file table. This causes the file table to be updated when events occur on the files in the table.

activateImpl

protected void activateImpl()

Called when a file table is activated. Subclasses can override this to add any listeners that are necessary to update the file table.

deactivate

public void deactivate()

Deactivate this file table.

deactivateImpl

protected void deactivateImpl()

Called when a file is deactivated. Subclasses can override this to remove any listeners that were added on activation.

getStorage

public Storage getStorage()

Get underlying storage used to store the file data.

Returns:

the underlying storage

getStorageKey

public abstract java.lang.String getStorageKey()

Get a unique identifier for this file table. This can be used to store and retrieve information about the files in this table.

Returns:

the unique identifier for the table

getChangesSince

public abstract void getChangesSince(int version,
                                     long cookie,
                                     @NotNull
                                     FileChangeListener listener)
                              throws java.lang.InterruptedException,
                                     FileChangesExpiredException,
                                     java.io.IOException

Get the changes since an older version of the file data. If the version passed to this method is FIRST_VERSION, the listener will be invoked with FileChange.Type.ADDEDchanges for every file. If the version passed to this method is REMOVED_VERSION, the listener will be invoked with FileChange.Type.REMOVED changes for every file.

The cookie parameter is used to ensure that the version number from the caller is consistent with the data stored in the table. For example, if the file table data was deleted and regenerated since the last time the method was called, the cookie will be different. If the cookie from the caller does not match the current cookie, the method will throw FileChangesExpiredException. The client can then delete and regenerate their own data so it matches the current state of the file table. The cookie parameter is ignored if the version is FIRST_VERSION, and can be any value in that case.

This method will never throw FileChangesExpiredException if the version passed into the method is FIRST_VERSION.

In certain cases, if there have been multiple changes to a file since the version being queried, the listener may receive unexpected events. Specifically:

• If a file has been deleted, then created again since the last version queried by the caller, the listener will receive an ADDED event, though from the caller's perspective the file has only changed. If the listener receives an ADDED event for a file it has previously received an ADDED event for, it should consider the file changed.
• If a file has been created, then deleted since the last version queried by the caller, the listener will receive a REMOVED event, though from the caller's perspective the file never existed. If the listener receives a REMOVED event for a file it has never seen before, it should ignore the event.
• If a file has been created, then modified since the last version queried by the caller, the listener will receive a CHANGED event, though from the caller's perspective the file has been added. If the listener receives a CHANGED event for a file it has never seen before, it should consider the file added.

Calls to this method may require updating the file data, which can take some time.

WARNING: This can be a long running operation. Callers of this method must take steps to ensure that the event thread is not blocked waiting for this method to return. Just making this call on a background thread is not sufficient. Callers must also ensure that no locks are held at the time this call is made, which could cause the event thread to block if it needs the same lock.

Parameters:

version - the file table version

cookie - the file table cookie

listener - the listener to be called with changes

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

FileChangesExpiredException - if the file change data for the file system version has expired

java.io.IOException - if the file table could not be read

See Also:

FileChanges.getVersion(), FileChanges.getCookie()

getId

public abstract int getId(@NotNull
                          java.net.URL url)
                   throws java.lang.InterruptedException,
                          java.io.IOException

Get the ID of a file in this table. Returns INVALID_FILE_ID if the URL is not in this table.

Parameters:

url - the URL of the file

Returns:

the ID of the file, or INVALID_FILE_ID if the URL is not in this table

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be read

getURL

public abstract java.net.URL getURL(int id)
                             throws java.lang.InterruptedException,
                                    java.io.IOException

Get the URL for a file ID in this file table. May return null if the ID does not exist in this file table. This may occur for IDs that were formerly in the table, but whose file has since been deleted.

Parameters:

id - the file ID

Returns:

the URL of the file, or null if the ID does not exist in this table

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be read

getLength

public abstract long getLength(int id)
                        throws java.lang.InterruptedException,
                               java.io.IOException

Get the length of a file in this file table.

Parameters:

id - the file ID

Returns:

the length of the file, or -1 if not known

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be read

getLastModified

public abstract long getLastModified(int id)
                              throws java.lang.InterruptedException,
                                     java.io.IOException

Get the last modified time of a file in this file table.

Parameters:

id - the file ID

Returns:

the last modified time of the file, or -1 if not known

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be read

getRelativePath

public abstract java.lang.String getRelativePath(java.net.URL url)

Get the path of a URL relative to the root of this file table. This does not check for existance of the URL.

Parameters:

url - the URL

Returns:

the relative path, or null if the URL cannot be made relative to this file table

delete

public abstract void delete()

Delete the file table from storage. This should only be called if it is known that the table is no longer needed. This migth occur, for example, if a directory is removed from a file scope by the user.

refresh

public void refresh()
             throws java.lang.InterruptedException,
                    java.io.IOException

Description copied from interface: FileScope

Refresh this scope. This brings the scope up to date with the current state of the files on disk. This is a very time consuming operation, and should not be called unless necesary. Clients of the File Change API should rarely, if ever, have a reason to call this method. It should typically only be called if the user has specifically requested that the files be refreshed. This should never be called on the event thread.

Specified by:

refresh in interface FileScope

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the refresh fails

invalidate

public abstract void invalidate()

Invalidates the file table. This should be called if it is known that files in the table have changed. Calling this unnecessarily can lead to performance problems, as it will cause the file table to be refreshed.

adjustTimestamps

public abstract void adjustTimestamps()
                               throws java.lang.InterruptedException,
                                      java.io.IOException

Adjust the timestamps stored in this file table. This is useful when moving file table data from one machine to another, when there may be discrepancies between the time configuration of the machines.

Throws:

java.lang.InterruptedException

java.io.IOException

invalidateFileImpl

protected abstract void invalidateFileImpl(java.net.URL file,
                                           boolean isBufferChange)

Invalidates a file in this file table.

Parameters:

file - the file to be invalidated

isBufferChange - whether the change is in memory only

invalidateDirectoryImpl

protected abstract void invalidateDirectoryImpl(java.net.URL directory,
                                                boolean includeSubdirectories,
                                                java.net.URL renameHintOldURL,
                                                java.net.URL renameHintNewURL)

Invalidates a directory in this file table. The default implementation schedules a background refresh of the file table. Subclasses may override this method to provide different behavior.

Parameters:

directory - the directory to be invalidated

includeSubdirectories - whether to invalidate subdirectories recursively

renameHintOldURL - the new location of the file if the directory invalidation is due to a file being renamed

renameHintNewURL - the old location of the file if the directory invalidation is due to a file being renamed

refreshFile

protected abstract void refreshFile(java.net.URL file,
                                    boolean isBufferChange)
                             throws java.lang.InterruptedException,
                                    java.io.IOException

Synchronously refresh the file table data for a specific file. This should be called when the caller knows that specific file has changed, and needs the updated information to be part of a subsequent file table operation. This should not be called when a file is added or removed. In those cases, call refreshDirectory(java.net.URL, boolean, java.net.URL, java.net.URL) on the parent directory instead.

Parameters:

file - the file to refresh

isBufferChange - whether the file change is known to be in memory only and not saved to disk

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be refreshed

refreshDirectory

protected abstract void refreshDirectory(java.net.URL directory,
                                         boolean includeSubdirectories,
                                         java.net.URL renameHintOldURL,
                                         java.net.URL renameHintNewURL)
                                  throws java.lang.InterruptedException,
                                         java.io.IOException

Synchronously refresh the file table data for a specific directory. This should be called when the caller knows that specific directory contains changes, and needs the updated information to be part of a subsequent file table operation.

Parameters:

directory - the directory to refresh

includeSubdirectories - whether to recursively refresh subdirectories

renameHintOldURL - the file being renamed in this directory, if the refresh is due to a file being renamed

renameHintNewURL - the new location of the renamed file, if the refresh is due to a file being renamed

Throws:

java.lang.InterruptedException - if the calling thread is interrupted

java.io.IOException - if the file table could not be refreshed

invokeListeners

protected void invokeListeners(FileChanges changes)

Invoke the listeners on this file table with a set of changes.

Parameters:

changes - the changes

invokeListener

protected void invokeListener(FileChangeListener listener,
                              FileChanges changes)

Invoke a specific listener with a set of changes.

Parameters:

listener - the listener

changes - the changes

getFileTables

public java.util.Collection<FileTable> getFileTables()

Description copied from interface: FileScope

Get the file tables currently used by this scope. A scope may span multiple file tables.

Specified by:

getFileTables in interface FileScope

Returns:

the file tables used by this scope

getFileTable

public FileTable getFileTable(java.net.URL url)

Description copied from interface: FileScope

Get the file table in this scope containing a particular URL.

Specified by:

getFileTable in interface FileScope

Parameters:

url - the URL

Returns:

the storage containing the URL, or null if no storages contain that URL