# LockManagerMultiplexerImpl.java

    /*
    ** Module   : LockManagerMultiplexerImpl.java
    ** Abstract : Handles server-to-server requests for record lock management
    **
    ** Copyright (c) 2004-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --JPRM-- ----------------------------------Description-----------------------------------
    ** 001 ECF 20071018  @35553  Created initial version. Handles server to server requests for record
    **                           lock management.
    ** 002 ECF 20071016  @35911  Completed implementation of the initialize() method. Registers the
    **                           singleton instance of this class as a network server object.
    ** 003 ECF 20071128  @36055  Replace LockType with int for method return values and parameters.
    **                           This prevents us from having to support LockType as Serializable
    **                           objects, which is desirable for several reasons:
    **                           1) less data to send over the network;
    **                           2) allows us to avoid creating multiple instances of each LockType
    **                              type, avoiding a lot of unnecessary working set.
    ** 004 VMN 20130830          Added lockTable method.
    ** 005 ECF 20131028          Import change.
    ** 006 ECF 20200906          New ORM implementation.
    ** 007 OM  20241128          Multi-tenant runtime support: selected the proper persistence context, eventually
    **                           based on [sharedDb] parameter.
    */

    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.persist.remote;

    import com.goldencode.p2j.net.*;
    import com.goldencode.p2j.persist.*;
    import com.goldencode.p2j.persist.lock.*;

    /**
     * A singleton instance of this class services server-to-server requests for
     * database record lock management.  This instance is registered as a remote
     * object and serves record lock management requests for one or more databases
     * which the server authoritatively manages.
     * <p>
     * Service requests may originate from more than one external server, so this
     * implementation is threadsafe.
     *
     * @author ECF
     */
    public final class LockManagerMultiplexerImpl
    extends DatabaseMultiplexer<LockManager<String>>
    implements LockManagerMultiplexer<String>
    {
       /** Singleton instance of this class */
       private static LockManagerMultiplexer<String> instance = null;

       /**
        * Initialize the lock manager multiplexer for this server instance.  This
        * method is to be called during server bootstrap, but not before the local
        * database manager has been initialized.
        * <p>
        * This method enforces the singleton pattern.
        *
        * @throws  IllegalStateException
        *          if this method is invoked more than once.
        */
       public static synchronized void initialize()
       {
          if (instance != null)
          {
             throw new IllegalStateException(
                "Lock manager multiplexer already initialized for this process");
          }

          instance = new LockManagerMultiplexerImpl();
          RemoteObject.registerNetworkServer(LockManagerMultiplexer.class, instance);
       }

       /**
        * Default constructor which initializes the resources needed for this
        * multiplexer to service lock manager requests.
        */
       private LockManagerMultiplexerImpl()
       {
          super();
       }

       /**
        * Lock or release a single database record in the current context. The record is uniquely
        * identified by a table name and record ID (i.e., primary key).  Whether the record is locked
        * or released depends upon the lock type requested: {@code LockType.NONE} is used to release
        * a record; any other lock type is used to lock a record.  Specifying {@code LockType.NONE}
        * for a record not locked in the current context is logically a no-op, though some overhead
        * is required for the check, and the caller may block waiting on the lock table monitor.
        * <p>
        * Before obtaining any record lock, {@code lockTable(LockType.SHARE, table, true)} is
        * invoked to acquire a share lock on the table. After releasing any record lock, {@code
        * lockTable(LockType.NONE, table, true)} is invoked to release that lock.
        * <p>
        * Any normal return from this method indicates the requested lock was acquired (or released)
        * successfully. Any error will result in an exceptional return. In the event a
        * record cannot be locked due to a conflicting lock held by another context, the current
        * thread will block until the lock is acquired, unless the requested lock is a "no-wait"
        * variant, in which case an exception is thrown.
        * <p>
        * This method also operates in a check-only mode (if {@code update} is set to {@code false})
        * where it goes through the motions of obtaining the specified lock type, but does not
        * actually change the lock status. This is at best an unreliable check, since another
        * context can change the lock status as soon as the lock status monitor is released, rendering
        * the check stale. Nevertheless, it exists to mimic the effect of the lock type option to the
        * Progress can-find function.
        *
        * @param   database
        *          Value that uniquely identifies the target database on the
        *          remote server.
        * @param   lockType
        *          Type of lock to be obtained.  <code>LockType.NONE</code> is
        *          used to release an existing lock, and to continue with no
        *          lock.
        * @param   ident
        *          ID which uniquely identifies the record being locked.
        * @param   update
        *          <code>true</code> if the lock state for the current record
        *          should be updated;  else <code>false</code>.
        *
        * @throws  LockUnavailableException
        *          if a "no-wait" lock cannot be acquired immediately.
        */
       public void lock(int database, int lockType, RecordIdentifier<String> ident, boolean update)
       throws LockUnavailableException
       {
          LockType lt = LockType.fromInt(lockType);
          lookupWorker(database).lock(lt, ident, update);
       }

       /**
        * Lock or release a single database record in the current context. The record is uniquely
        * identified by a table name and record ID (i.e., primary key). Whether the record is locked
        * or released depends upon the lock type requested: {@code LockType.NONE} is used to release
        * a record; any other lock type is used to lock a record. Specifying {@code LockType.NONE}
        * for a record not locked in the current context is logically a no-op, though some overhead
        * is required for the check, and the caller may block waiting on the lock table monitor.
        * <p>
        * Before obtaining any record lock, {@code lockTable(LockType.SHARE, table, true)} is
        * invoked to acquire a share lock on the table. After releasing any record lock, {@code
        * lockTable(LockType.NONE, table, true)} is invoked to release that lock.
        * <p>
        * Any normal return from this method indicates the requested lock was acquired (or released)
        * successfully. Any error or timeout will result in an exceptional return. In the event a
        * record cannot be locked due to a conflicting lock held by another context, the current
        * thread will block until the lock is acquired, unless either (a) the requested lock is a
        * "no-wait" variant; or (b) a positive timeout value was provided and at least that number
        * of milliseconds has elapsed without acquiring the lock. In either case, an exception is
        * thrown as described below.
        * <p>
        * This method also operates in a check-only mode (if {@code update} is set to {@code false})
        * where it goes through the motions of obtaining the specified lock type, but does not
        * actually change the lock status. This is at best an unreliable check, since another
        * context can change the lock status as soon as the lock status monitor is released, rendering
        * the check stale. Nevertheless, it exists to mimic the effect of the lock type option to the
        * Progress can-find function.
        *
        * @param   database
        *          Value that uniquely identifies the target database on the
        *          remote server.
        * @param   lockType
        *          Type of lock to be obtained.  <code>LockType.NONE</code> is
        *          used to release an existing lock, and to continue with no
        *          lock.
        * @param   ident
        *          ID which uniquely identifies the record being locked.
        * @param   update
        *          <code>true</code> if the lock state for the current record
        *          should be updated;  else <code>false</code>.
        * @param   timeout
        *          Positive number of milliseconds to wait before throwing {@link
        *          LockTimeoutException}, or 0L to wait indefinitely. Ignored if a no-wait lock
        *          variant is requested.
        *
        * @throws  LockUnavailableException
        *          if a "no-wait" lock cannot be acquired immediately.
        */
       public void lock(int database,
                        int lockType,
                        RecordIdentifier<String> ident,
                        boolean update,
                        long timeout)
       throws LockUnavailableException
       {
          LockType lt = LockType.fromInt(lockType);
          lookupWorker(database).lock(lt, ident, update, timeout);
       }

       /**
        * Attempt to obtain the specified lock type on a table. If the lock cannot be obtained
        * immediately, the current thread will block until the lock becomes available and is
        * obtained, unless the requested lock type is a "no-wait" lock.  In the latter case,
        * an exception is raised, indicating that the lock is not available. The current thread
        * continues once the lock is obtained.
        * <p>
        * A lock currently held can be released by specifying
        * <code>LockType.NONE</code> for the <code>lockType</code> parameter.
        * <p>
        * Method returns previous lock type (so that calling code knows what to set it back to after
        * bulk delete).
        * The normal return of this method indicates that the lock request (or lack thereof)
        * completed successfully, and that the current context now holds a lock of the requested
        * type.
        *
        * @param   database
        *          Value that uniquely identifies the target database on the remote server.
        * @param   lockType
        *          Type of lock to be obtained.  <code>LockType.NONE</code> is used to release
        *          an existing lock, and to continue with no lock.
        * @param   table
        *          Table name.
        * @param   update
        *          <code>true</code> if the lock state for the current record should be updated;
        *          else <code>false</code>.
        *
        * @throws  LockUnavailableException
        *          if a "no-wait" lock cannot be acquired immediately.
        *
        * @return  previous lock type.
        */
       public LockType lockTable(int database, int lockType, String table, boolean update)
       throws LockUnavailableException
       {
          LockType lt = LockType.fromInt(lockType);
          return lookupWorker(database).lockTable(lt, table, update);
       }

       /**
        * Query the lock type currently held by the current context for the
        * specified database record.
        * <p>
        * This method should always return the <b>non-</b><code>NO_WAIT</code>
        * variants of a lock type.  That is, even if the actual lock type is
        * <code>LockType.EXCLUSIVE_NO_WAIT</code> or
        * <code>LockType.SHARE_NO_WAIT</code>, the simpler types of
        * <code>LockType.EXCLUSIVE</code> and <code>LockType.SHARE</code>,
        * respectively, should be returned.  The lack of a lock is required to
        * return <code>LockType.NONE</code> rather than <code>null</code>.
        *
        * @param   database
        *          Value that uniquely identifies the target database on the
        *          remote server.
        * @param   ident
        *          ID which uniquely identifies the record being queried.
        *
        * @return  The lock type currently held by the current context, never
        *          <code>null</code>.
        */
       public int queryLock(int database, RecordIdentifier<String> ident)
       {
          LockType lt = lookupWorker(database).queryLock(ident);

          return LockType.toInt(lt);
       }

       /**
        * Get the lock manager which is associated with the given database.
        *
        * @param   database
        *          Physical database with which the returned worker is associated.
        *
        * @return  Worker object to which service requests associated with the
        *          given database must be delegated.
        */
       protected LockManager<String> getWorker(Database database)
       {
          Persistence p = PersistenceFactory.getInstance(database);

          return p.getLockManager(!database.isTenant());
       }
    }