RemoteLockManager.java
/*
** Module : RemoteLockManager.java
** Abstract : LockManager implementation which delegates to a remote server
**
** Copyright (c) 2004-2020, Golden Code Development Corporation.
**
** -#- -I- --Date-- --JPRM-- ----------------------------Description-----------------------------
** 001 ECF 20071018 @35555 Created initial version. LockManager
** implementation which delegates to a remote
** server.
** 002 ECF 20071128 @36056 Modified calls to LockManagerMultiplexer to
** comply with API changes.
** 003 ECF 20090801 @43501 Added getLockAdminstrator(). Always returns null,
** since administration of remote lock managers is
** not supported.
** 004 VMN 20130830 Added lockTable method.
** 005 ECF 20131031 Added setLockListener method to satisfy LockManager interface, but it
** is not supported in this remote implementation.
** 006 ECF 20160820 Added lock method variant with timeout.
** 018 ECF 20200906 New ORM implementation.
** 019 IAS 20200906 Fixed type 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 java.io.*;
import com.goldencode.p2j.persist.*;
import com.goldencode.p2j.persist.lock.*;
/**
* A specialized implementation of {@link
* com.goldencode.p2j.persist.lock.LockManager LockManager} which delegates
* requests for database record locking services to the remote P2J server
* which is authoritative for the target database. This is necessary in cases
* where business logic dynamically connects to a remote database which is not
* managed by the current P2J server instance, since record lock actions must
* be serialized through a lock manager which is authoritative for the target
* database.
* <p>
* An instance of this class works with a local proxy for a remote instance of
* {@link LockManagerMultiplexer} residing at the target server. The remote
* object may manage multiple databases, each of which is assigned a unique
* database identifier. When the database is {@link #setDatabase(Database)
* set} into a <code>RemoteLockManager</code> instance, the associated
* identifier is requested from the remote multiplexer. The ID returned by
* the multiplexer is used on all subsequent service requests sent by the
* <code>RemoteLockManager</code> instance.
*
* @see RemotePersistence
* @author ECF
* @param <T>
* table reference type
*/
public final class RemoteLockManager<T extends Serializable>
implements LockManager<T>
{
/** Lock manager multiplexer which will service remote requests */
private final LockManagerMultiplexer<T> multiplexer;
/** Multiplex ID for the remote database associated with this object */
private int mpID = -1;
/**
* Constructor which stores a proxy to the remote object which will
* service lock manager requests for the remote database.
*
* @param multiplexer
* Lock manager multiplexer which will service remote requests.
*/
public RemoteLockManager(LockManagerMultiplexer<T> multiplexer)
{
this.multiplexer = multiplexer;
}
/**
* Set the name of the physical database with which this lock manager is
* associated.
*
* @param database
* Database information object.
*/
public void setDatabase(Database database)
{
if (mpID >= 0)
{
throw new IllegalStateException("Database can only be set once");
}
mpID = multiplexer.getMultiplexID(database.getName());
}
/**
* Register a lock listener, which will receive notifications of changes in lock status for any
* record managed by this object.
* <p>
* Remote lock update notifications are not supported, so this method will throw an exception
* if invoked.
*
* @param listener
* Listener to be registered or <code>null</code> to deregister the current listener.
*
* @throws UnsupportedOperationException
* always.
*/
public void setLockListener(LockListener listener)
{
throw new UnsupportedOperationException();
}
/**
* Retrieve the {@link LockAdministrator} object associated with this
* <code>LockManager</code> instance.
* <p>
* This implementation returns <code>null</code>; the administration of a
* remote lock manager is not supported.
*
* @return <code>null</code>.
*/
public LockAdministrator getLockAdministrator()
{
return null;
}
/**
* 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 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(LockType lockType, RecordIdentifier<T> ident, boolean update)
throws LockUnavailableException
{
int type = LockType.toInt(lockType);
multiplexer.lock(mpID, type, 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 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.
*/
@Override
public void lock(LockType lockType, RecordIdentifier<T> ident, boolean update, long timeout)
throws LockUnavailableException,
LockTimeoutException
{
int type = LockType.toInt(lockType);
multiplexer.lock(mpID, type, 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 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 table 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(LockType lockType, T table, boolean update)
throws LockUnavailableException
{
int type = LockType.toInt(lockType);
return multiplexer.lockTable(mpID, type, 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 ident
* ID which uniquely identifies the record being queried.
*
* @return The lock type currently held by the current context, never
* <code>null</code>.
*/
public LockType queryLock(RecordIdentifier<T> ident)
{
int type = multiplexer.queryLock(mpID, ident);
return LockType.fromInt(type);
}
}