com.gos4j
Interface Goal

public interface Goal

This interface represents a single pass at a goal within the system.

The successful completion of goals involves the transition from a ready to start state into an in progress state and then finally to a completed state. To enable these transitions use the start() and complete() methods.

So that the scheduling system knows how to arrange the execution of the associated threads each lifecycle of a goal has a duration and/or a deadline. Using the setTargetDuration(...) and setTargetDeadline(...) methods you can define the goal objective (even after the goal scheduling has started).

To optimize the progress of goals to their deadlines the progress of the goal needs to be reported to the scheduler. To do this use setProgressPercentage(...) or setProgressProportion(...).

Also in special circumstances progress may not be measurable, for this type of goal progress use the staged interfaces.

Important: you must either complete() or abort() all Goal objects. Failing to do this might render the scheduling ineffective owing to the number of dead goals it would be trying to manage.

Usage:

   // the goal
   Goal payBill = ...;
   
   // now say when the target end time is
   payBill.setTargetDeadline(dueDate);
 
   // then begin the processing
   payBill.start();
 
   try {
     waitForPayDay();
     payBill.setProgressPercentage(60);
     writePaymentSlip();
     payBill.setProgressPercentage(70);
     sendPaymentSlip();
     payBill.setProgressPercentage(95);
     waitForDebitOfFunds();
 
     // and thats it
     payBill.complete();
 
   } catch (Throwable t) {
     t.printStackTrace();
     // can't leave a dead goal lying around
     payBill.abort();
   }
 
 

Author:

Hugh@hughreid.com 27-May-2003

Method Summary

void	abort() This indicates that the goal processing has ended abnormally.
void	complete() This indicates that the goal processing has completed successfully.
int	getProgressPercentage() The provides the current progress.
float	getProgressProportion() This provide the current progress.
java.lang.Object	getProgressStage() This provides the current progress.
boolean	isInProgress() This checks that the goal has been started but not yet completed or aborted.
boolean	isPastStage(java.lang.Object stage) This check whether the progress has passed the supplied stage.
boolean	isReadyToStart() This checks that the goal has not already been started.
boolean	isStaged() This indicates that the goal progress is measured in distinct stages.
void	setProgressPercentage(int percent) This indicates the level of progress that the goal processing has made.
void	setProgressProportion(float proportion) This indicates the level of progress that the goal processing has made.
void	setProgressStage(java.lang.Object stage) This indicates the level of progress that the goal processing has made.
void	setTargetDeadline(long deadline) This sets the target deadline of the goal.
void	setTargetDuration(long duration) This updates the target duration of the goal.
void	start() This indicates that the goal processing has started.

Method Detail

setTargetDuration

public void setTargetDuration(long duration)

This updates the target duration of the goal. This is used to define a deadline relative to the start time.

Parameters:

duration - the length of time in milliseconds.

setTargetDeadline

public void setTargetDeadline(long deadline)

This sets the target deadline of the goal. This overrides the duration settings.

Parameters:

deadline - the new deadline time.

start

public void start()

This indicates that the goal processing has started.

abort

public void abort()

This indicates that the goal processing has ended abnormally.

complete

public void complete()

This indicates that the goal processing has completed successfully.

isReadyToStart

public boolean isReadyToStart()

This checks that the goal has not already been started.

Returns:

true if the start() method can be called.

isInProgress

public boolean isInProgress()

This checks that the goal has been started but not yet completed or aborted.

Returns:

true if the start() method has been called.

setProgressPercentage

public void setProgressPercentage(int percent)

This indicates the level of progress that the goal processing has made.

Parameters:

percent - the integer percentage of progress (0 - 100).

setProgressProportion

public void setProgressProportion(float proportion)

This indicates the level of progress that the goal processing has made.

Parameters:

proportion - the floating point representation (0.0 - 1.0).

getProgressPercentage

public int getProgressPercentage()

The provides the current progress.

Returns:

the percentage completed as reported (0 - 100)

getProgressProportion

public float getProgressProportion()

This provide the current progress.

Returns:

the proportion completed as reported (0.0 - 1.0)

isStaged

public boolean isStaged()

This indicates that the goal progress is measured in distinct stages.

Returns:

true if the goal progress is measured in stages.

isPastStage

public boolean isPastStage(java.lang.Object stage)

This check whether the progress has passed the supplied stage.

Parameters:

stage - the stage to have passed.

Returns:

true if the stage has been passed.

setProgressStage

public void setProgressStage(java.lang.Object stage)

This indicates the level of progress that the goal processing has made.

Parameters:

stage - the stage reached.

getProgressStage

public java.lang.Object getProgressStage()

This provides the current progress.

Returns:

the stage of progress as reported.