org.sapia.ubik.util
Class StartStopLock

java.lang.Object
  org.sapia.ubik.util.StartStopLock

public class StartStopLock
extends java.lang.Object

An instance of this class is used to synchronized start/stop operations. It is common for such operations to be wholly or in part performed in separate threads. An instance of this class can be used to synchronized threads that invoke start or stop operations, and those that actually perform these operations.

USAGE:

Suppose we are implementing a server that can be embedded. The server itself will run in a separate thread. The application that will use the server will be responsible for starting and stopping it.

First, our server thread implementation:

 public class ServerThread extends Thread{
   private StartStopLock _lock
   
   public ServerThread(StartStopLock lock){
     _lock = lock;
   }
   
   public void run(){
   
     boolean started = false;
     while(!_lock.stopRequested && !interrupted()){
       if(!started){
        _lock.notifyStarted(null);
        started = true;
       }
       // do work...
     }
     
     // here do shutdown stuff...
     
     _lock.notifyStopped(null);
   }
 }
 

Third, we create the actual server class that will be used by application code:

 public class Server{
   private StartStopLock _lock = new StartStopLock();
   private ServerThread _thread;
   
   public void start() throws Exception{
     _thread = new ServerThread(_lock);
     _thread.start();
     _lock.waitStarted();
   }
   
   public void stop() throws Exception{
     _thread.interrupt();
     _lock.triggerStopped();
     _lock.waitStopped();
   }
 }
 

Author:

Yanick Duchesne

Copyright:

Copyright © 2002-2005 Sapia Open Source Software. All Rights Reserved.

License:

Read the license.txt file of the jar or visit the license page at the Sapia OSS web site

Nested Class Summary

static interface

StartStopLock.StopRequestListener

Field Summary

boolean	started
boolean	stopped
boolean	stopRequested

Constructor Summary

StartStopLock()

StartStopLock(StartStopLock.StopRequestListener listener)

Method Summary

boolean	isStarted()
boolean	isStopped()
boolean	isStopRequested()
void	notifyStarted(java.lang.Throwable err)
void	notifyStopped(java.lang.Throwable err)
void	triggerStop() This method internally sets the stopRequested flag to true, calls this instance's encapsulated StopRequestListener, and notifies threads that are currently blocking on the waitStopped() method.
void	waitStarted() Blocks until this instance's started flag is set to true, or until a startup error is signaled.
void	waitStarted(long timeout) Blocks until this instance's started flag is set to true, or until a startup error is signaled.
void	waitStopped() Blocks until this instance's stopped flag is set to true, or until a startup error is signaled.
void	waitStopped(long timeout) Blocks until this instance's stopped flag is set to true, or until a startup error is signaled.

Methods inherited from class java.lang.Object

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

Field Detail

started

public boolean started

stopped

public boolean stopped

stopRequested

public boolean stopRequested

Constructor Detail

StartStopLock

public StartStopLock(StartStopLock.StopRequestListener listener)

Parameters:

listener - a StopRequestListener that is called upon this instance's triggerStop method being called.

See Also:

StartStopLock.StopRequestListener

StartStopLock

public StartStopLock()

Method Detail

isStarted

public boolean isStarted()

Returns:

true if the started flag is on.

isStopped

public boolean isStopped()

Returns:

true if the stopped flag is on.

isStopRequested

public boolean isStopRequested()

Returns:

true if the stopRequested flag is on.

triggerStop

public void triggerStop()

This method internally sets the stopRequested flag to true, calls this instance's encapsulated StopRequestListener, and notifies threads that are currently blocking on the waitStopped() method.

waitStarted

public void waitStarted(long timeout)
                 throws java.lang.InterruptedException,
                        java.lang.Throwable

Blocks until this instance's started flag is set to true, or until a startup error is signaled. If the given timeout has elapsed, this method exits.

Parameters:

timeout - a given amount of time to wait for this instance's started flag to be true.

Throws:

java.lang.InterruptedException - if the calling thread is interrupted while blocking.

java.lang.Throwable - if an error occurs at startup.

See Also:

notifyStarted(Throwable)

waitStarted

public void waitStarted()
                 throws java.lang.InterruptedException,
                        java.lang.Throwable

Blocks until this instance's started flag is set to true, or until a startup error is signaled.

Throws:

java.lang.InterruptedException - if the calling thread is interrupted while blocking.

java.lang.Throwable - if an error occurs at startup.

See Also:

notifyStarted(Throwable)

waitStopped

public void waitStopped(long timeout)
                 throws java.lang.InterruptedException,
                        java.lang.Throwable

Blocks until this instance's stopped flag is set to true, or until a startup error is signaled. If the given timeout has elapsed, this method exits.

Parameters:

timeout - a given amount of time to wait for this instance's stopped flag to be true.

Throws:

java.lang.InterruptedException - if the calling thread is interrupted while blocking.

java.lang.Throwable - if an error occurs while stopping.

See Also:

#notifyStopped(Throwable)(Throwable)

waitStopped

public void waitStopped()
                 throws java.lang.InterruptedException,
                        java.lang.Throwable

Blocks until this instance's stopped flag is set to true, or until a startup error is signaled.

Throws:

java.lang.InterruptedException - if the calling thread is interrupted while blocking.

java.lang.Throwable - if an error occurs while stopping.

See Also:

notifyStopped(Throwable)

notifyStarted

public void notifyStarted(java.lang.Throwable err)

Parameters:

err - a Throwable

notifyStopped

public void notifyStopped(java.lang.Throwable err)

Parameters:

err - a Throwable