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());
}
}