com.sage.accpac.sm
Interface Multiuser

@ThreadSafe
public interface Multiuser

Provides facilities to control multi-user access to ACCPAC. Multi-user access is controlled by performing locking on predefined resources.

An object of this class cannot be created directly by applications. It should be obtained from the Program object's getMultiuser() method.

Locking can be done on the following resources:

• A specific resource identified by a resource string.
• An application's data. This is always identified by the database, together with the 2-letter application ID.
• An organization's data. This is always identified by the database.

The behaviour of the resource functions is different from the behaviour of the functions addressing the application's or organization's data.

Avoid using the Multiuser object if possible. Locking should be done by views rather than by UIs. Locking is especially dangerous when ACCPAC is running remotely over the internet.

Using this object after the owning Program has been disposed results in undefined behaviour.

See Also:

Program.getMultiuser() method.

Thread safety

Thread-safe

Method Summary

boolean	lockApp(DBLink.LinkType orgType, java.lang.String appID, boolean exclusive) Locks an application's data shared or exclusive.
boolean	lockOrg(DBLink.LinkType orgType, boolean exclusive) Locks an organization's data shared or exclusive.
boolean	lockRsc(java.lang.String resource, boolean exclusive) Locks a named resource shared or exclusive.
boolean	regradeApp(DBLink.LinkType orgType, java.lang.String appID, boolean upgrade) Upgrades or downgrades an existing lock on an application's data.
boolean	regradeOrg(DBLink.LinkType orgType, boolean upgrade) Upgrades or downgrades an existing lock on an organization's data.
void	unlockApp(DBLink.LinkType orgType, java.lang.String appID) Unlocks an application's data that was previously locked.
void	unlockOrg(DBLink.LinkType orgType) Unlocks an organization's data that was previously locked.
void	unlockRsc(java.lang.String resource) Unlocks a previously locked named resource.

Method Detail

lockApp

boolean lockApp(DBLink.LinkType orgType,
                java.lang.String appID,
                boolean exclusive)

Locks an application's data shared or exclusive.

Call lockApp only when the application's data is not already locked by the program. To upgrade or downgrade an existing lock on the application's data use regradeApp.

Parameters:

orgType - Organization type of the database.

appID - the program ID (application selector) of the application whose data you wish to lock. This must consist of two upper case letters.

exclusive - Indicates whether to lock the application's data in exclusive mode. If specified as false, the application's data will be locked in shared mode.

Returns:

Returns true if the call has successfully locked the application's data and false if it has failed to lock it for some reason (other than those resulting in an exception being thrown). Almost certainly the reason will be that someone else has already locked it inconsistently with the desired mode.

Throws:

java.lang.IllegalStateException - if the application's data is already locked by the program.

lockOrg

boolean lockOrg(DBLink.LinkType orgType,
                boolean exclusive)

Locks an organization's data shared or exclusive.

Call lockOrg only when the organization's data is not already locked by the program. To upgrade or downgrade an existing lock on the organization's data use regradeOrg.

Parameters:

orgType - Organization type of the database.

exclusive - Indicates whether to lock the organization's data in exclusive mode. If specified as false, the organization's data will be locked in shared mode.

Returns:

Returns true if the call has successfully locked the application's data and false if it has failed to lock it for some reason (other than those resulting in an exception being thrown). Almost certainly the reason will be that someone else has already locked it inconsistently with the desired mode.

Throws:

java.lang.IllegalStateException - if the organization's data is already locked by the program.

lockRsc

boolean lockRsc(java.lang.String resource,
                boolean exclusive)

Locks a named resource shared or exclusive.

If the program does not have the resource locked then the method will attempt to lock the resource either shared or exclusive, depending on the exclusive argument.

If the program already has the resource locked in the requested mode the function will return true.

If the program already has the resource locked shared and requests that the resource be locked exclusive then the function will attempt so to do. If it succeeds it will return true. If it fails it will return false and will leave the resource locked shared.

If the program already has the resource locked exclusive and requests that the resource be locked shared then the function will request that the lock be downgraded to shared and will return true.

Note that this is different from the behaviour of lockApp and lockOrg. Resource locking does not involve a regrade function and the locks are not nested; you only need to call unlockRsc once to unlock the resource. no matter how many calls to lockRsc there have been since the last call to unlockRsc (if any).

Parameters:

resource - The resource to lock. The resource name should consist only of printable ASCII characters and should be at most 20 characters long. It should not begin with the characters @SEM-.

exclusive - Indicates whether to lock the resource in exclusive mode. Specifying false locks the resource in shared mode.

Returns:

Returns true if the call has successfully locked the resource and false if it has failed to lock it for some reason (other than those resulting in an exception being thrown). Almost certainly the reason will be that someone else has already locked it inconsistently with the desired mode.

Throws:

java.lang.IllegalArgumentException - if the resource parameter is not valid in some way (other than that indicated by IllegalCharacterException), for example a null reference or a string that is reserved for locking applications or companies.

regradeApp

boolean regradeApp(DBLink.LinkType orgType,
                   java.lang.String appID,
                   boolean upgrade)

Upgrades or downgrades an existing lock on an application's data.

The caller must already have locked the application's data.

Calls to regradeApp may be nested. If the caller initially has shared access, nested calls to upgrade and then restore the caller's lock will result in the data being locked exclusively until the outermost level of nested calls restores the lock, returning it to shared access.

Parameters:

orgType - Organization type of the database.

appID - the program ID (application selector) of the application whose data you wish to lock. This must consist of two upper case letters.

upgrade - Indicates whether to upgrade a shared lock to exclusive. If specified as false, the routine downgrades an exclusive lock to shared mode.

Returns:

Returns true if the call has successfully regraded the lock and false otherwise. If returning false then the lock will remain as it was (i.e. if upgrade was true then the shared lock will still be in place).

Throws:

java.lang.IllegalStateException - if the program did not have the organization's data locked suitably (i.e. if upgrade was true but the caller did not have a share lock or if upgrade was false but the caller did not have an exclusive lock).

regradeOrg

boolean regradeOrg(DBLink.LinkType orgType,
                   boolean upgrade)

Upgrades or downgrades an existing lock on an organization's data.

The caller must already have locked the organization's data.

Calls to regradeOrg may be nested. If the caller initially has shared access, nested calls to upgrade and then restore the caller's lock will result in the data being locked exclusively until the outermost level of nested calls restores the lock, returning it to shared access.

Parameters:

orgType - Organization type of the database.

upgrade - Indicates whether to upgrade a shared lock to exclusive. If specified as false, the routine downgrades an exclusive lock to shared mode.

Returns:

Returns true if the call has successfully regraded the lock and false otherwise. If returning false then the lock will remain as it was (i.e. if upgarde was true then the shared lock will still be in place).

Throws:

java.lang.IllegalStateException - if the program did not have the organization's data locked suitably (i.e. if upgrade was true but the caller did not have a share lock or if upgrade was false but the caller did not have an exclusive lock).

unlockApp

void unlockApp(DBLink.LinkType orgType,
               java.lang.String appID)

Unlocks an application's data that was previously locked.

Parameters:

orgType - Organization type of the database.

appID - the program ID (application selector) of the application whose data you wish to lock. This must consist of two upper case letters.

Throws:

java.lang.IllegalStateException - if the program did not have the application's data locked.

unlockOrg

void unlockOrg(DBLink.LinkType orgType)

Unlocks an organization's data that was previously locked.

Parameters:

orgType - Organization type of the database.

Throws:

java.lang.IllegalStateException - if the program did not have the organization's data locked.

unlockRsc

void unlockRsc(java.lang.String resource)

Unlocks a previously locked named resource.

Parameters:

resource - The resource to unlock. This must be as passed to lockRsc.

Throws:

java.lang.IllegalStateException - if the program did not have the resource locked.