LockTableUpdater.UpdateWorker (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.persist.meta.LockTableUpdater.UpdateWorker

All Implemented Interfaces:

java.lang.Runnable

Enclosing class:

LockTableUpdater
```
private static class LockTableUpdater.UpdateWorker
extends java.lang.Object
implements java.lang.Runnable
```
A worker containing a queue to which record lock events are written from multiple user threads/contexts, and from which those events are read in a dedicated, daemon thread. The idea is to offload the potentially more time-consuming work of querying and updating the metadata database from a dedicated thread, to minimize any performance penalty of this work on user sessions. Since this naturally introduces the possibility of the lock metadata to get out of sync with the actual lock states in the lock manager, a synchronization mechanism is used to ensure any pending updates are flushed to the database before any query against this table is executed. This way, only those user sessions actually querying the lock metadata are affected by any lag in updating the metadata from record lock events.
Note that some analysis of the lock event has to occur in the user session in which the lock event occurred, but as much of the work as possible is deferred until the separate thread processes the events.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`LockTableUpdater.UpdateWorker.Handler` Invocation handler which delegates calls to the `LockTableUpdater.MinimalLock` proxy methods to the backing DMO instance.

Field Summary

Fields
Modifier and Type	Field and Description
`private static java.lang.Class<?>`	`dmoClass` MetaLockImpl DMO implementation class
`private static java.lang.String`	`dmoEntity` MetaLockImpl DMO entity name
`private boolean`	`done` Termination flag
`private java.util.List<RecordLockEvent>`	`eventQueue` Event queue to which many threads can write and from which only one thread reads
`private java.util.Map<java.lang.String,java.lang.Integer>`	`fileNums` Cache of converted table names to file numbers
`private LockTableUpdater.UpdateWorker.Handler`	`handler` Invocation handler which maps proxy method calls to underlying DMO methods
`private long`	`lastAddedID` Unique and sequential ID of the last event added to the queue
`private long`	`lastProcessedID` Unique and sequential ID of the last event read from the queue and processed
`private static java.lang.String`	`LOCK_TABLE` Metadata lock table name
`private static java.util.Map<java.lang.reflect.Method,java.lang.reflect.Method>`	`methodMap` Map of `MinimalLock` methods to `MetaLockImpl` methods
`private long`	`nextPrimaryKey` Next available primary key for a new lock metadata record
`private Persistence`	`persistence` Persistence helper object for metadata database
`private LockTableUpdater.MinimalLock`	`proxy` Proxy object for the current metadata lock DMO
`private java.lang.Object`	`readLock` Lock needed to read from queue; must be obtained first if write lock is needed also
`private static java.lang.String`	`SQL_FILENUM` SQL query to find a file number by converted table name (used by lock manager)
`private static java.lang.String`	`SQL_LOCK` SQL query to find a lock record by lock recid and user
`private AssociatedThread`	`workThread` Update worker thread
`private java.lang.Object`	`writeLock` Lock needed to write to queue; must be obtained second if read lock is needed also

Constructor Summary

Constructors
Constructor and Description

UpdateWorker(Persistence persistence)
Constructor.

Constructors
Constructor and Description
`UpdateWorker(Persistence persistence)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) void`	`addEvent(RecordLockEvent event)` Add a record lock event to the queue, locking out other write and read operations until the queue is updated.
`private Persistable`	`createRecord(RecordLockEvent event)` Create a metadata lock record for the given record lock event.
`private Persistable`	`findRecord(RecordLockEvent event)` Find the metadata lock record associated with the user ID and lock record ID specified by the given record lock event.
`(package private) void`	`forceFlush()` This method is called within a user context to force any pending lock events to be processed.
`private java.lang.Integer`	`getFileNum(RecordLockEvent event)` Get the file number associated with a lock event.
`private long`	`getLockRecordID(RecordLockEvent event)` Extract an integral lock record ID from the lock event.
`private void`	`processEvent(RecordLockEvent event)` Process an individual record lock event, updating the metadata lock table as appropriate.
`private void`	`processPendingEvents()` Process all pending record lock events in the queue.
`void`	`run()` This method executes in the worker thread, reading record lock events from the queue when they become available, and updating the metadata database accordingly.
`(package private) void`	`terminate()` Set a flag to terminate the queue, removing any pending events which have not yet been processed.

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

- Field Detail
  - LOCK_TABLE
```
private static final java.lang.String LOCK_TABLE
```
    Metadata lock table name
    
    See Also:
    
    Constant Field Values
  - SQL_LOCK
```
private static final java.lang.String SQL_LOCK
```
    SQL query to find a lock record by lock recid and user
    
    See Also:
    
    Constant Field Values
  - SQL_FILENUM
```
private static final java.lang.String SQL_FILENUM
```
    SQL query to find a file number by converted table name (used by lock manager)
    
    See Also:
    
    Constant Field Values
  - dmoClass
```
private static final java.lang.Class<?> dmoClass
```
    MetaLockImpl DMO implementation class
  - dmoEntity
```
private static final java.lang.String dmoEntity
```
    MetaLockImpl DMO entity name
  - methodMap
```
private static final java.util.Map<java.lang.reflect.Method,java.lang.reflect.Method> methodMap
```
    Map of MinimalLock methods to MetaLockImpl methods
  - eventQueue
```
private final java.util.List<RecordLockEvent> eventQueue
```
    Event queue to which many threads can write and from which only one thread reads
  - persistence
```
private final Persistence persistence
```
    Persistence helper object for metadata database
  - proxy
```
private final LockTableUpdater.MinimalLock proxy
```
    Proxy object for the current metadata lock DMO
  - handler
```
private final LockTableUpdater.UpdateWorker.Handler handler
```
    Invocation handler which maps proxy method calls to underlying DMO methods
  - workThread
```
private final AssociatedThread workThread
```
    Update worker thread
  - fileNums
```
private final java.util.Map<java.lang.String,java.lang.Integer> fileNums
```
    Cache of converted table names to file numbers
  - done
```
private boolean done
```
    Termination flag
  - readLock
```
private java.lang.Object readLock
```
    Lock needed to read from queue; must be obtained first if write lock is needed also
  - writeLock
```
private java.lang.Object writeLock
```
    Lock needed to write to queue; must be obtained second if read lock is needed also
  - lastAddedID
```
private long lastAddedID
```
    Unique and sequential ID of the last event added to the queue
  - lastProcessedID
```
private long lastProcessedID
```
    Unique and sequential ID of the last event read from the queue and processed
  - nextPrimaryKey
```
private long nextPrimaryKey
```
    Next available primary key for a new lock metadata record
- Constructor Detail
  - UpdateWorker
```
UpdateWorker(Persistence persistence)
```
    Constructor.
    
    Parameters:
    
    persistence - Persistence helper object for metadata database.
- Method Detail
  - run
```
public void run()
```
    This method executes in the worker thread, reading record lock events from the queue when they become available, and updating the metadata database accordingly.
    
    Specified by:
    
    run in interface java.lang.Runnable
  - addEvent
```
void addEvent(RecordLockEvent event)
```
    Add a record lock event to the queue, locking out other write and read operations until the queue is updated. Notify a the worker thread when the new event has been added.
    
    Parameters:
    
    event - Record lock event to be added.
  - forceFlush
```
void forceFlush()
```
    This method is called within a user context to force any pending lock events to be processed. It guarantees that any events that are pending in the queue at the time this method is invoked will have been processed by the time this method returns. However, other events may be added by other user contexts in the meantime, and these are not guaranteed to have been processed.
  - terminate
```
void terminate()
```
    Set a flag to terminate the queue, removing any pending events which have not yet been processed. The worker thread is interrupted.
    This method should invoked when the primary database associated with the enclosing lock table updater is deregistered, as part of cleaning up the associated metadata database.
  - processPendingEvents
```
private void processPendingEvents()
```
    Process all pending record lock events in the queue. Events are read and removed from the queue synchronously, such that no new events may be added during the read/remove operation. However, they are then processed asynchronously, so new events may be added while lock metadata is being updated.
  - processEvent
```
private void processEvent(RecordLockEvent event)
```
    Process an individual record lock event, updating the metadata lock table as appropriate. If the lock event represents a newly acquired lock, create a new lock record, otherwise find the existing lock record associated with the event, which must represent a change of the state of an existing lock. If that change of state represents a lock release, delete the associated lock record from the lock table.
    
    Parameters:
    
    event - Record lock event describing a new lock or a change in state of an existing lock.
  - getLockRecordID
```
private long getLockRecordID(RecordLockEvent event)
                      throws PersistenceException
```
    Extract an integral lock record ID from the lock event. This will be a positive value for records and a negative value for tables.
    
    Parameters:
    
    event - A record lock event.
    
    Returns:
    
    See above.
    
    Throws:
    
    PersistenceException
  - findRecord
```
private Persistable findRecord(RecordLockEvent event)
                        throws PersistenceException
```
    Find the metadata lock record associated with the user ID and lock record ID specified by the given record lock event.
    
    Parameters:
    
    event - Record lock event.
    
    Returns:
    
    Metadata lock record, if found.
    
    Throws:
    
    PersistenceException - if a lock record cannot be found for the given event, or if there is an error executing the query.
  - createRecord
```
private Persistable createRecord(RecordLockEvent event)
                          throws PersistenceException
```
    Create a metadata lock record for the given record lock event.
    
    Parameters:
    
    event - Event which specifies information to be stored in the lock record.
    
    Returns:
    
    New lock record.
    
    Throws:
    
    PersistenceException - if there is any error querying related metadata, or if there is a reflection error instantiating the DMO.
  - getFileNum
```
private java.lang.Integer getFileNum(RecordLockEvent event)
                              throws PersistenceException
```
    Get the file number associated with a lock event.
    
    Parameters:
    
    event - Record lock event.
    
    Returns:
    
    File number for the table associated with the event.
    
    Throws:
    
    PersistenceException

Class LockTableUpdater.UpdateWorker

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOCK_TABLE

SQL_LOCK

SQL_FILENUM

dmoClass

dmoEntity

methodMap

eventQueue

persistence

proxy

handler

workThread

fileNums

done

readLock

writeLock

lastAddedID

lastProcessedID

nextPrimaryKey

Constructor Detail

UpdateWorker

Method Detail

run

addEvent

forceFlush

terminate

processPendingEvents

processEvent

getLockRecordID

findRecord

createRecord

getFileNum