FsLockController (TrueZIP Kernel 7.5.1 API)

java.lang.Object
- de.schlichtherle.truezip.fs.FsController<M>
- - de.schlichtherle.truezip.fs.FsModelController<M>
  - - de.schlichtherle.truezip.fs.FsDecoratingController<FsLockModel,C>
    - - de.schlichtherle.truezip.fs.FsLockModelDecoratingController<FsController<? extends FsLockModel>>
      - de.schlichtherle.truezip.fs.FsLockController

```
@Immutable
public final class FsLockController
extends FsLockModelDecoratingController<FsController<? extends FsLockModel>>
```
Provides read/write locking for multi-threaded access by its clients.

Since:

TrueZIP 7.5

Author:

Christian Schlichtherle

See Also:
FsLockModel, FsNeedsWriteLockException

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private class`	`FsLockController.GetClosedIcon`
`private class`	`FsLockController.GetOpenIcon`
`private class`	`FsLockController.Input`
`private static interface`	`FsLockController.IOOperation<T>`
`private class`	`FsLockController.IsReadOnly`
`private class`	`FsLockController.LockInputStream`
`private class`	`FsLockController.LockOutputStream`
`private class`	`FsLockController.LockReadOnlyFile`
`private class`	`FsLockController.LockSeekableByteChannel`
`private class`	`FsLockController.Nio2Input`
`private class`	`FsLockController.Nio2Output`
`private class`	`FsLockController.Output`
`private static class`	`FsLockController.SocketFactory`
`private static class`	`FsLockController.ThreadLocalUtilFactory`
`private static class`	`FsLockController.ThreadUtil`

Field Summary

Fields
Modifier and Type	Field and Description
`private static BitField<FsSyncOption>`	`NOT_WAIT_CLOSE_IO`
`private ReentrantReadWriteLock.ReadLock`	`readLock`
`private static FsLockController.SocketFactory`	`SOCKET_FACTORY`
`private static ThreadLocal<FsLockController.ThreadUtil>`	`threadUtil`
`private ReentrantReadWriteLock.WriteLock`	`writeLock`

Fields inherited from class de.schlichtherle.truezip.fs.FsLockModelDecoratingController
WAIT_TIMEOUT_MILLIS

Fields inherited from class de.schlichtherle.truezip.fs.FsDecoratingController
delegate

Constructor Summary

Constructors
Constructor and Description

FsLockController(FsController<? extends FsLockModel> controller)
Constructs a new file system lock controller.

Constructors
Constructor and Description
`FsLockController(FsController<? extends FsLockModel> controller)` Constructs a new file system lock controller.

Method Summary

Methods
Modifier and Type	Method and Description
`(package private) void`	`close(Closeable closeable)`
`Icon`	`getClosedIcon()` Deprecated.
`FsEntry`	`getEntry(FsEntryName name)` Returns the file system entry for the given name or `null` if it doesn't exist.
`InputSocket<?>`	`getInputSocket(FsEntryName name, BitField<FsInputOption> options)` Returns an input socket for reading the contents of the file system entry addressed by the given name from the file system.
`Icon`	`getOpenIcon()` Deprecated.
`OutputSocket<?>`	`getOutputSocket(FsEntryName name, BitField<FsOutputOption> options, Entry template)` Returns an output socket for writing the contents of the entry addressed by the given name to the file system.
`boolean`	`isExecutable(FsEntryName name)` Returns `false` if the named file system entry is not executable.
`boolean`	`isReadable(FsEntryName name)` Returns `false` if the named file system entry is not readable.
`boolean`	`isReadOnly()` Returns `true` if and only if the file system is read-only.
`boolean`	`isWritable(FsEntryName name)` Returns `false` if the named file system entry is not writable.
`private <T> T`	`locked(FsLockController.IOOperation<T> operation, Lock lock)` Tries to call the given consistent operation while holding the given lock.
`void`	`mknod(FsEntryName name, Entry.Type type, BitField<FsOutputOption> options, Entry template)` Creates or replaces and finally links a chain of one or more entries for the given entry `name` into the file system.
`protected ReentrantReadWriteLock.ReadLock`	`readLock()`
`(package private) <T> T`	`readLocked(FsLockController.IOOperation<T> operation)`
`(package private) <T> T`	`readOrWriteLocked(FsLockController.IOOperation<T> operation)`
`void`	`setReadOnly(FsEntryName name)` Sets the named file system entry as read-only.
`boolean`	`setTime(FsEntryName name, BitField<Entry.Access> types, long value, BitField<FsOutputOption> options)` Makes an attempt to set the last access time of all types in the given bit field for the file system entry with the given name.
`boolean`	`setTime(FsEntryName name, Map<Entry.Access,Long> times, BitField<FsOutputOption> options)` Makes an attempt to set the last access time of all types in the given map for the file system entry with the given name.
`<X extends IOException> void`	`sync(BitField<FsSyncOption> options, ExceptionHandler<? super FsSyncException,X> handler)` Commits all unsynchronized changes to the contents of this file system to its parent file system, releases the associated resources (e.g. target archive files) for access by third parties (e.g. other processes), cleans up any temporary allocated resources (e.g. temporary files) and purges any cached data.
`void`	`unlink(FsEntryName name, BitField<FsOutputOption> options)` Removes the named file system entry from the file system.
`protected ReentrantReadWriteLock.WriteLock`	`writeLock()`
`(package private) <T> T`	`writeLocked(FsLockController.IOOperation<T> operation)`

Methods inherited from class de.schlichtherle.truezip.fs.FsLockModelDecoratingController
checkWriteLockedByCurrentThread, isWriteLockedByCurrentThread

Methods inherited from class de.schlichtherle.truezip.fs.FsDecoratingController
getParent, toString

Methods inherited from class de.schlichtherle.truezip.fs.FsModelController
getModel, getMountPoint, isTouched, setTouched

Methods inherited from class de.schlichtherle.truezip.fs.FsController
equals, hashCode, sync, sync

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - NOT_WAIT_CLOSE_IO
```
private static final BitField<FsSyncOption> NOT_WAIT_CLOSE_IO
```
  - readLock
```
private final ReentrantReadWriteLock.ReadLock readLock
```
  - SOCKET_FACTORY
```
private static final FsLockController.SocketFactory SOCKET_FACTORY
```
  - threadUtil
```
private static final ThreadLocal<FsLockController.ThreadUtil> threadUtil
```
  - writeLock
```
private final ReentrantReadWriteLock.WriteLock writeLock
```
- Constructor Detail
  - FsLockController
```
public FsLockController(FsController<? extends FsLockModel> controller)
```
    Constructs a new file system lock controller.
    
    Parameters:
    controller - the decorated file system controller.
- Method Detail
  - close
```
void close(Closeable closeable)
     throws IOException
```
    Throws:
    
    IOException
  - getClosedIcon
```
@Deprecated
public Icon getClosedIcon()
                   throws IOException
```
    Deprecated.
    
    Description copied from class: FsController
    
    Returns a nullable icon representing the "closed" state when displaying the (federated) file system represented by this controller in a GUI, e.g. a JTree.
    
    Overrides:
    
    getClosedIcon in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Returns:
    The nullable icon.
    
    Throws:
    
    IOException - on any I/O failure.
  - getEntry
```
public FsEntry getEntry(FsEntryName name)
                 throws IOException
```
    Description copied from class: FsController
    
    Returns the file system entry for the given name or null if it doesn't exist. Modifying the returned entry does not show any effect on the file system and may result in an UnsupportedOperationException.
    
    Overrides:
    
    getEntry in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the name of the file system entry.
    
    Returns:
    A file system entry or null if no file system entry exists for the given name.
    
    Throws:
    
    IOException - on any I/O failure.
  - getInputSocket
```
public InputSocket<?> getInputSocket(FsEntryName name,
                            BitField<FsInputOption> options)
```
    Description copied from class: FsController
    
    Returns an input socket for reading the contents of the file system entry addressed by the given name from the file system.
    
    Overrides:
    
    getInputSocket in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the file system entry name.
    options - the input options.
    
    Returns:
    An InputSocket.
  - getOpenIcon
```
@Deprecated
public Icon getOpenIcon()
                 throws IOException
```
    Deprecated.
    
    Description copied from class: FsController
    
    Returns a nullable icon representing the "open" state when displaying the (federated) file system represented by this controller in a GUI, e.g. a JTree.
    
    Overrides:
    
    getOpenIcon in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Returns:
    The nullable icon.
    
    Throws:
    
    IOException - on any I/O failure.
  - getOutputSocket
```
public OutputSocket<?> getOutputSocket(FsEntryName name,
                              BitField<FsOutputOption> options,
                              @CheckForNull
                              Entry template)
```
    Description copied from class: FsController
    
    Returns an output socket for writing the contents of the entry addressed by the given name to the file system. If template is not null, then the output entry shall have as many of its properties copied as reasonable, e.g. the last modification time.
    
    Overrides:
    
    getOutputSocket in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - a file system entry name.
    options - a bit field of output options.
    template - a nullable template for the properties of the output entry.
    
    Returns:
    An OutputSocket.
  - isExecutable
```
public boolean isExecutable(FsEntryName name)
                     throws IOException
```
    Description copied from class: FsController
    
    Returns false if the named file system entry is not executable.
    The implementation in the class FsController always returns false.
    
    Overrides:
    
    isExecutable in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the name of the file system entry.
    
    Returns:
    false if the named file system entry is not executable.
    
    Throws:
    
    IOException - on any I/O failure.
  - isReadable
```
public boolean isReadable(FsEntryName name)
                   throws IOException
```
    Description copied from class: FsController
    
    Returns false if the named file system entry is not readable.
    
    Overrides:
    
    isReadable in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the name of the file system entry.
    
    Returns:
    false if the named file system entry is not readable.
    
    Throws:
    
    IOException - on any I/O failure.
  - isReadOnly
```
public boolean isReadOnly()
                   throws IOException
```
    Description copied from class: FsController
    
    Returns true if and only if the file system is read-only.
    
    Overrides:
    
    isReadOnly in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Returns:
    true if and only if the file system is read-only.
    
    Throws:
    
    IOException - on any I/O failure.
  - isWritable
```
public boolean isWritable(FsEntryName name)
                   throws IOException
```
    Description copied from class: FsController
    
    Returns false if the named file system entry is not writable.
    
    Overrides:
    
    isWritable in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the name of the file system entry.
    
    Returns:
    false if the named file system entry is not writable.
    
    Throws:
    
    IOException - on any I/O failure.
  - locked
```
private <T> T locked(FsLockController.IOOperation<T> operation,
           Lock lock)
          throws IOException
```
    Tries to call the given consistent operation while holding the given lock.
    If this is the first execution of this method on the call stack of the current thread, then the lock gets acquired using Lock.lock(). Once the lock has been acquired the operation gets called. If this fails for some reason and the thrown exception chain contains a FsNeedsLockRetryException, then the lock gets temporarily released and the current thread gets paused for a small random time interval before this procedure starts over again. Otherwise, the exception chain gets just passed on to the caller.
    If this is not the first execution of this method on the call stack of the current thread, then the lock gets acquired using Lock.tryLock() instead. If this fails, an FsNeedsLockRetryException gets created and passed to the given exception handler for mapping before finally throwing the resulting exception by executing throw handler.fail(new FsNeedsLockRetryException()). Once the lock has been acquired the operation gets called. If this fails for some reason then the exception chain gets just passed on to the caller.
    This algorithm prevents dead locks effectively by temporarily unwinding the stack and releasing all locks for a small random time interval. Note that this requires some minimal cooperation by the operation: Whenever it throws an exception, it MUST leave its resources in a consistent state so that it can get retried again! Mind that this is standard requirement for any FsController.
    
    Type Parameters:
    T - The return type of the operation.
    Parameters:
    operation - The atomic operation.
    lock - The lock to hold while calling the operation.
    
    Returns:
    The result of the operation.
    
    Throws:
    
    IOException - As thrown by the operation.
    
    FsNeedsLockRetryException - See above.
  - mknod
```
public void mknod(FsEntryName name,
         Entry.Type type,
         BitField<FsOutputOption> options,
         Entry template)
           throws IOException
```
    Description copied from class: FsController
    
    Creates or replaces and finally links a chain of one or more entries for the given entry name into the file system.
    Overrides:
    
    mknod in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the file system entry name.
    type - the file system entry type.
    options - the file system output options. If FsOutputOption.CREATE_PARENTS is set, any missing parent directories will be created and linked into the file system with its last modification time set to the system's current time.
    template - if not null, then the file system entry at the end of the chain shall inherit as much properties from this entry as possible - with the exception of its name and type.
    
    Throws:
    IOException - on any I/O failure, including but not limited to these reasons:
    
    The file system is read only.
    name contains characters which are not supported by the file system.
    The entry already exists and either the option FsOutputOption.EXCLUSIVE is set or the entry is a directory.
    The entry exists as a different type.
    A parent entry exists but is not a directory.
    A parent entry is missing and createParents is false.
  - readLock
```
protected ReentrantReadWriteLock.ReadLock readLock()
```
    Overrides:
    
    readLock in class FsLockModelDecoratingController<FsController<? extends FsLockModel>>
  - readLocked
```
<T> T readLocked(FsLockController.IOOperation<T> operation)
       throws IOException
```
    Throws:
    
    IOException
  - readOrWriteLocked
```
<T> T readOrWriteLocked(FsLockController.IOOperation<T> operation)
              throws IOException
```
    Throws:
    
    IOException
  - setReadOnly
```
public void setReadOnly(FsEntryName name)
                 throws IOException
```
    Description copied from class: FsController
    
    Sets the named file system entry as read-only. This method will fail for typical federated (archive) file system controller implementations because they do not support it.
    
    Overrides:
    
    setReadOnly in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the name of the file system entry.
    
    Throws:
    
    IOException - on any I/O failure or if this operation is not supported.
  - setTime
```
public boolean setTime(FsEntryName name,
              BitField<Entry.Access> types,
              long value,
              BitField<FsOutputOption> options)
                throws IOException
```
    Description copied from class: FsController
    
    Makes an attempt to set the last access time of all types in the given bit field for the file system entry with the given name. If false is returned or an IOException is thrown, then still some of the last access times may have been set. Whether or not this is an atomic operation is specific to the implementation.
    
    Overrides:
    
    setTime in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the file system entry name.
    types - the access types.
    value - the last access time.
    options - the file system output options.
    
    Returns:
    true if and only if setting the access time for all types in types succeeded.
    
    Throws:
    
    IOException - on any I/O failure.
  - setTime
```
public boolean setTime(FsEntryName name,
              Map<Entry.Access,Long> times,
              BitField<FsOutputOption> options)
                throws IOException
```
    Description copied from class: FsController
    
    Makes an attempt to set the last access time of all types in the given map for the file system entry with the given name. If false is returned or an IOException is thrown, then still some of the last access times may have been set. Whether or not this is an atomic operation is specific to the implementation.
    
    Overrides:
    
    setTime in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the file system entry name.
    times - the access times.
    options - the file system output options.
    
    Returns:
    true if and only if setting the access time for all types in times succeeded.
    
    Throws:
    
    IOException - on any I/O failure.
  - sync
```
public <X extends IOException> void sync(BitField<FsSyncOption> options,
                                ExceptionHandler<? super FsSyncException,X> handler)
          throws IOException
```
    Description copied from class: FsController
    
    Commits all unsynchronized changes to the contents of this file system to its parent file system, releases the associated resources (e.g. target archive files) for access by third parties (e.g. other processes), cleans up any temporary allocated resources (e.g. temporary files) and purges any cached data. Note that temporary resources may get allocated even if the federated file systems were accessed read-only. If this is not a federated file system, i.e. if its not a member of a parent file system, then nothing happens. Otherwise, the state of this file system controller is reset.
    
    Overrides:
    
    sync in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Type Parameters:
    X - The type of the IOException to throw at the discretion of the exception handler.
    Parameters:
    options - a bit field of synchronization options.
    handler - the exception handling strategy for consuming input FsSyncExceptions and mapping them to output IOExceptions.
    
    Throws:
    
    IOException - on any other (not necessarily I/O related) failure.
  - unlink
```
public void unlink(FsEntryName name,
          BitField<FsOutputOption> options)
            throws IOException
```
    Description copied from class: FsController
    
    Removes the named file system entry from the file system. If the named file system entry is a directory, it must be empty.
    
    Overrides:
    
    unlink in class FsDecoratingController<FsLockModel,FsController<? extends FsLockModel>>
    
    Parameters:
    name - the file system entry name.
    options - output options for this operation.
    
    Throws:
    
    IOException - on any I/O failure.
  - writeLock
```
protected ReentrantReadWriteLock.WriteLock writeLock()
```
    Overrides:
    
    writeLock in class FsLockModelDecoratingController<FsController<? extends FsLockModel>>
  - writeLocked
```
<T> T writeLocked(FsLockController.IOOperation<T> operation)
        throws IOException
```
    Throws:
    
    IOException

Class FsLockController

Nested Class Summary

Field Summary

Fields inherited from class de.schlichtherle.truezip.fs.FsLockModelDecoratingController

Fields inherited from class de.schlichtherle.truezip.fs.FsDecoratingController

Constructor Summary

Method Summary

Methods inherited from class de.schlichtherle.truezip.fs.FsLockModelDecoratingController

Methods inherited from class de.schlichtherle.truezip.fs.FsDecoratingController

Methods inherited from class de.schlichtherle.truezip.fs.FsModelController

Methods inherited from class de.schlichtherle.truezip.fs.FsController

Methods inherited from class java.lang.Object

Field Detail

NOT_WAIT_CLOSE_IO

readLock

SOCKET_FACTORY

threadUtil

writeLock

Constructor Detail

FsLockController

Method Detail

close

getClosedIcon

getEntry

getInputSocket

getOpenIcon

getOutputSocket

isExecutable

isReadable

isReadOnly

isWritable

locked

mknod

readLock

readLocked

readOrWriteLocked

setReadOnly

setTime

setTime

sync

unlink

writeLock

writeLocked