Proposal for new output connector locking API (2010-06-11 07:00Z by Ilari):

* Remove OutputConnectorLocking.

* OutputConnector interface:

** public OutputConnectorLock getLock()

*** Obtain lock object corresponding to this connector interface.

* OutputConnectorLock class:

** This class models source side of output connector lock. One such object exists per
** output connector. There's also dummy lock that never becomes lockable (null lock).

** public <init>()
*** Construct new lock.

** public void holdOutput()
*** Wait until all clients have first obtained the lock using waitOutput()
*** or pollOutput() and then released it using releaseOutput() or releaseOutputWaitAll()
*** and then return. While some thread is in call to holdOutput() on some lock, the lock
*** is said to be "lockable".

* OutputConnectorLockClient class:

** This class models consumer side of output connector lock. One such object exists per
** consumer. The lock can be either "unlocked" or "locked". Each consumer is associated
** with one "source-side" lock (which may be dummy one), and all locks that are associated
** with given lock are called "clients" of lock. Locks are not exclusive, multiple
** clients of the same lock can be locked at once.

** Client can be locked only once per call to holdOutput(). If multiple attempts are made,
** the subsequent attempts will not see the associated lock as lockable until holdOutput() is
** called again. This does not apply if associated lock has just been changed (in this case,
** the associated lock is seen as lockable/not lockable as it is).

** public <init>()
*** Construct new lock client. Initially the lock is "unlocked" and associated with dummy
*** lock that's never lockable.

** public boolean waitOutput()
*** If interrupt flag is set, interrupt flag is cleared and method returns false immediately,
*** otherwise waits for either associated lock to be lockable or interrupt flag to rise. If
*** associated lock becomes lockable, lock is locked and waitOutput() returns true. If
*** interrupt flag rises before that, interrupt flag is cleared, lock is left unlocked and
*** waitOutput() returns false.
*** If lock is already locked, there is pending lock attempt or lock is waiting for other
*** locks to unlock, waitOutput() throws IllegalStateException.

** public boolean pollOutput()
*** If associated lock is lockable, lock is locked and pollOutput() returns true. If
*** associated lock is not lockable, pollOutput() leaves lock unlocked and returns false.
*** pollOutput() ignores interrupt flag. 
*** If lock is already locked, there is pending lock attempt or lock is waiting for other
*** locks to unlock, pollOutput() throws IllegalStateException.

** public void releaseOutput()
*** If lock is locked, it is released.
*** If lock is unlocked, releaseOutput() throws IllegalStateException.

** public void releaseOutputWaitAll()
*** If lock is locked, it is released, and releaseOutputWaitAll() waits until all
*** consumers of associated lock have released (locking them before that) their locks.
*** If lock is unlocked, releaseOutputWaitAll() throws IllegalStateException.

** public void interrupt()
*** Sets (rises) interrupt flag.

** public void clearInterrupt()
*** Clears interrupt flag.

** public void reattach(OutputConnectorLock lock)
*** Changes the associated lock. If lock is locked, the change takes effect immediately
*** after lock is unlocked and other clients of assoicated lock have been waited for (in
*** case of releaseOutputWaitAll()). If lock is unlocked (even if inside waitOutput()),
*** the change takes effect immediately (i.e. in case of locks with waitOutput() call
*** active, the call immediately switches to waiting the new associated lock).
*** If lock is null, the associated lock will be dummy lock that is never lockable.