oracle.jdeveloper.jot
Interface JotFileLock

All Known Subinterfaces:

JotFile

public interface JotFileLock

It is extremely important that users are aware that some locks in JotFileLock interact with text buffer locks. Code utilizing the jot, and its locking MUST NOT simultaneously directly use the text buffer's locks. This will expose the thread to deadlocks.

JotFileLock provides mechanisms to lock the Jot model for a particular file, and to lock the underlying source buffer. It is necessary for all clients of the Jot to use an appropriate lock for either reading, or writing to the JotFile

The JotFileLock interface is a slightly modified implementation of a read/write lock, or shared/exclusive lock. The underlying implementation performs reference counding for threads, and absolutely requires that each call to readLockModel(), readLockFile(), and writeLock() are paired with an equal number of calls to readUnlockModel(), readUnlockFile(), and writeUnlock().

There are two types of read locks available. readLockModel() only locks the Jot model. In the event that the JotFile represents a source buffer, or editable form of the compilation unit, this buffer will be left unlocked, and other threads may modify it. readLockFile() will lock both the Jot model, and the underlying editable buffer, if such a buffer exists.

In general, both kinds of read locks will allow multiple threads to acquire the same level of read lock simultaneously. Additionally, a thread is permitted to acquire a readLockModel() while another thread holds a readLockFile().

However, it is important to note that the two types of read locks are not interchangable. Acquisition of a readLockModel() will prevent another thread from being allowed either readLockFile(), or writeLock(). This is because both of those calls may cause the Jot model to update, if it is out of date with the file. A thread holding a readLockModel() may upgrade its lock to any level, provided no other thread also holds the same level of lock. A thread holding readLockFile() may upgrade to a writeLock() provided no other thread currently holds any level of read lock.

writeLock() always locks both the model and the file, it is also granted exculsively to one thread.

Calls to all locking methods will always perfrom their desired result, provided the JotFile is both existent, and represents a lockable compilation unit. However, if the conditions do not allow the call to succeed immediately, the thread will be made to wait.

Method Summary

boolean	isLockable() All JotFile units are extensions of JotFileLock.
void	readLockFile() The most common read lock.
void	readLockModel() This type of read lock should only be used when the client wishes to allow concurrent source modification, such as user typing.
void	readUnlockFile() Removes a single reference count for a readLockFile.
void	readUnlockModel() Removes a single reference count for a readLockModel.
void	writeLock() Write lock will be granted when no other thread has any kind of lock.
void	writeUnlock() Removes a single reference count for a writeLock.

Method Detail

isLockable

public boolean isLockable()
                   throws JotInvalidElementException

All JotFile units are extensions of JotFileLock. Unfortunately, not all JotFile units may be locked, or modified.

Returns:

true if this unit may be locked, otherwise false.

Throws:

JotInvalidElementException

readLockFile

public void readLockFile()
                  throws JotInvalidElementException

The most common read lock. This lock maintains reference counting, and also locks the underlying file. Each call to readLockFile() must be paired with a call to readUnlockFile()

Throws:

JotInvalidElementException

readUnlockFile

public void readUnlockFile()
                    throws JotInvalidElementException

Removes a single reference count for a readLockFile.

Throws:

JotInvalidElementException

writeLock

public void writeLock()
               throws JotInvalidElementException

Write lock will be granted when no other thread has any kind of lock. A thread having a write lock will disallow any other thread obtaining any level of lock. writeLock() locks both the model and the underlying file. Each writeLock() must be paired with a call to writeUnlock(). When the write lock count reaches zero an update message will be sent, if an update occured while the unit was locked.

Throws:

JotInvalidElementException

writeUnlock

public void writeUnlock()
                 throws JotInvalidElementException

Removes a single reference count for a writeLock. When the write lock count reaches zero an update message will be sent, if an update occured while the unit was locked.

Throws:

JotInvalidElementException

readLockModel

public void readLockModel()
                   throws JotInvalidElementException

This type of read lock should only be used when the client wishes to allow concurrent source modification, such as user typing. This lock maintains reference counting, but only locks the Jot model. Each call to readLockModel() must be paired with a call to readUnlockModel()

Throws:

JotInvalidElementException

readUnlockModel

public void readUnlockModel()
                     throws JotInvalidElementException

Removes a single reference count for a readLockModel.

Throws:

JotInvalidElementException