arlut.csd.ganymede
Class loginSemaphore

java.lang.Object
  |
  +--arlut.csd.ganymede.loginSemaphore

public final class loginSemaphore

extends java.lang.Object

This class provides a handy counting semaphore used to arbitrate user login access to the GanymedeServer. The server uses a single loginSemaphore to safely handle schema edits and server shutdowns.

Field Summary

private int	count How many users are logged in on this semaphore?
(package private) static boolean	debug
private java.lang.String	disableMsg If this var is not null, we are disabled.

Constructor Summary

loginSemaphore()

Method Summary

java.lang.String	checkEnabled() Gated enabled test.
void	decrement() Decrement the login count.
java.lang.String	disable(java.lang.String message, boolean waitForZero, long millis) disables logins
void	enable(java.lang.String message) re-enables logins.
int	getCount() Returns a count of the number of users logged in on this semaphore
java.lang.String	increment(long millis) Attempt to increment the login count

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

debug

static final boolean debug

count

private int count

How many users are logged in on this semaphore?

disableMsg

private java.lang.String disableMsg

If this var is not null, we are disabled. The String here will hold the reason why.

Constructor Detail

loginSemaphore

public loginSemaphore()

Method Detail

disable

public java.lang.String disable(java.lang.String message,
                                boolean waitForZero,
                                long millis)
                         throws java.lang.InterruptedException

disables logins

This method turns off user logins in Ganymede. A piece of code in the Ganymede server can call disable() on this object to signal that no further logins or schema edits should be allowed.

Parameters:

message - An explanation of why logins are being disabled.

waitForZero - If true, disable may block until the count of users logged in goes to zero. If false, disable will disable further increments, but the disable call itself will not block until this time

millis - If waitForZero is true, tells us about our blocking behavior.. if millis < 0, we will block as long as necessary. if millis = 0, we will not block. if millis > 0, we will block no more than that number of milliseconds.

Returns:

returns null if the disable was successful, or else a descriptive string if the disable couldn't be carried out

enable

public void enable(java.lang.String message)

re-enables logins.

Parameters:

message - Should be identical to the message used to disable logins, to verify that the right code is doing the re-enabling.

Throws:

java.lang.IllegalStateException - throws an IllegalStateException if the message parameter did not match that used to disable the semaphore

checkEnabled

public java.lang.String checkEnabled()

Gated enabled test. If this method returns null, logins are allowed at the time checkEnabled() is called. This method is to be used by admin consoles, which should not connect to the server during schema editing or server shut down, but which should not affect the login count for reasons of blocking a schema edit disable, say.

Returns:

null if logins are currently enabled, or a message string if they are disabled.

getCount

public int getCount()

Returns a count of the number of users logged in on this semaphore

increment

public java.lang.String increment(long millis)
                           throws java.lang.InterruptedException

Attempt to increment the login count

Parameters:

millis - Controls blocking behavior on this call.. if millis < 0, we will block forever until the semaphore is re-enabled. if millis == 0, no blocking will be peformed. if millis > 0, we will not block for longer than that number of milliseconds.

Returns:

An explanation of why the increment could not be carried out, or null if the increment was successful.

decrement

public void decrement()

Decrement the login count.

This can be done when the semaphore is enabled or disabled, but if the semaphore count is already zero, an IllegalStateException will be thrown.