docs: public final boolean tryLock()
      throws LockFile.FileSecurityException,
             LockFile.LockHeldExternallyException,
             LockFile.UnexpectedFileNotFoundException,
             LockFile.UnexpectedEndOfFileException,
             LockFile.UnexpectedFileIOException, LockFile.WrongLengthException,
             LockFile.WrongMagicException {
  
          if (this.locked) {
              return true;
          }
  
          try {
              pollHeartbeat();
              openRAF();
  
              // Must come *after* openRAF to comply with the
              // doOptionalLockActions() PRE: assertion contract.
              //
              // <sigh> In an ideal world, it would be possible from Java to open
              // a file handle and obtain at least one associated NIO FileLock in
              // one kernel-enforced atomic operation.  However, we can't even
              // guarantee that NIO is available.
              //
              // Note:
              // The NIOLockFile version of this operation is 'self cleaning'...
              // if it fails for some reason, then it does a 'best effort' to
              // eagerly release and nullify its FileLock object before
              // returning.
              doOptionalLockActions();
  
              // Inlined the following to reduce potential for timing issues
              // such as initial timer thread startup induced delay of first
              // pulse.
              //
              // In general, what we'll get is two initial pulses in rapid
              // sucession: one here and one an instant later as a result of
              // startHeartbeat (which is OK... no harm, and it's one-shot
              // behaviour, not repeated on every writeHeartbeat)
              //
              // Unfortunately, we may occasionally encounter astronomic (at least
              // in computer time) delays between invocation of startHeartbeat
              // and the time at which effort is actually expended toward writing
              // the initial MAGIC and heartbeat timestamp values.
              //
              // Another good reason to inline the first writeHeartbeat is to
              // provide a last line of defence against inter-process as well
              // as inter-thread race conditions.  That is, exceptions thrown in
              // HeartbeatRunner.run() do yet get propagated anywhere useful.
              //
              // Of course, if we are operating under a fully-featured and correct
              // NIO implementation, the concerns described above are really
              // non-issues... at this point, we will have (at least in theory) a
              // valid OS-enforced file lock.
              //
              // But in an ideal world (with or without NIO), any pulse failure in
              // HeartbeatRunner.run() would flag the database Logger that a
              // database lock condition violation has occured, preventing further
              // ad-hoc operation of the database.
              //
              // The problem is, if a lock condition has been violated that is
              // being used by a database instance, what mechanism can be used to
              // safely checkpoint, backup and/or shut down that instance?  For
              // all we know, the violation indicates that another instance is now
              // happily writing to the other database files...
              //
              // A prudent course of action to take under detection of a
              // cooperative lock condition violation in the heartbeatRunner task
              // would be to perform a 'SCRIPT <file>' to some pre-ordained 'safe'
              // backup location using a globally unique file name and then do a
              // 'SHUTDOWN IMMEDIATELY' in one database-scope atomic context (e.g.
              // a single JDBC statement execution).
              //
              // However, by the time a lock condition violation has been detected,
              // the data cache file (and log/script) may already be quite
              // corrupted, meaning the resulting script may be totally inaccurate
              // or worse.
              //
              // Bottom line:
              //
              // Regardless of this inlining measure, if a lock violation occurs
              // after startHeartbeat, it's almost certain there's much worse in
              // store...
              writeMagic();
              writeHeartbeat();
              FileUtil.getDefaultInstance().deleteOnExit(file);
  
              this.locked = true;
  
              startHeartbeat();
          } finally {
              if (!locked) {
  
                  // No harm in this...
                  //
                  // If this LockFile is an NIOLockFile instance and
                  // doOptionalLockActions() failed above, then a 'best
                  // effort' optional release was already perfomed and
                  // this will be a no-op.
                  //
                  // On the other hand, if doOptionalLockActions() succeeded, best
                  // to undo them here right away, since the core locking work
                  // failed.
                  //
                  // In practice, however, it is very unlikely for the core
                  // locking work to fail if this LockFile is an NIOLockFile
                  // instance and doOptionalLockActions() succeeded, except
                  // under JVM implementations whose NIO package is broken in
                  // a very specific way.
                  //
                  // Other possibilities include unfortunate timing of events
                  // under certain network file system or removable media
                  // configurations, device umounts, physical removal of storage
                  // media, Java security or file system security policy
                  // updates, etc.
                  doOptionalReleaseActions();
  
                  try {
                      closeRAF();
                  } catch (Exception ex) {
  
                      // It's too late to do anything useful with this exception.
                      //
                      // we've already/ failed and will let the caller know the
                      // reason via the exception thrown in the try block.
                      //
                      // ex.printStackTrace();
                  }
              }
          }
  
          return this.locked;
      }