com.sharkysoft.fig.extra.dev

Class UnderConstructionException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.sharkysoft.fig.extra.dev.NotImplementedException

com.sharkysoft.fig.extra.dev.UnderConstructionException

All Implemented Interfaces:

Serializable

public class UnderConstructionException
extends NotImplementedException

Indicates an unfinished execution path.

Details: An UnderConstructionException is thrown when a method is called, a case invoked, or a feature is requested that has not yet been implemented. This class is the extreme programmer's best friend; it allows the developer to compile and execute half-baked code while minimizing the risk of forgetting to finish it later. More importantly, this class allows you to completely design and reference a class without implementing any of it. To do this, simply include the statement...

throw new UnderConstructionException();

...in any method or execution path that you'd like to finish later. The compiler will let you compile the code without forcing you to insert dummy return values or "TODO" comments that you might forget about later.

Example 1:

if (readyToRock) {
  do_stuff();
  do_more_stuff();
}
else
  throw new UnderConstructionException();
     

In Example 1, a single execution path has been left unimplemented because the programmer is not yet concerned about it. He'll get to it later, and if he forgets, he'll be reminded when it's needed.

Example 2:

public static float[] findPolynomialRoots(Polynomial polynomial) { 
  // I'm putting this declaration here so that the rest of my code will compile, 
  // but I'll implement the body later or ask my partner to do it.
  throw new UnderConstructionException();
}
     

In Example 2, a method is stubbed out because the developer knows he's going to need it, but he doesn't want to focus on its implementation right now. In situations like this, you may be tempted to stub out the method and return a dummy value, such as null or 0. Don't! Doing so is asking for trouble! You might forget about it and wind up with a difficult-to-trace bug! Just use UnderConstructionException instead, and rest confident that the JVM will remind you if your forgotten method ever gets executed. In fact, you won't just be reminded, but you'll also be pointed to the class, method, and line number!

Example 3:

public void actionPerformed(ActionEvent event) { 
  // We're safe doing nothing for now, but eventually we'll need to
  // implement this.
  UnderConstructionException.trace("Warning: button response not implemented.");
}
     

In Example 3, a button's action event handler has not yet been implemented. At this stage in the application development, however, the programmer has decided that this is not a problem. Rather than stopping the show with an exception, the developer has decided to simply let UnderConstructionException issue a reminder that the handler has not yet been implemented.

Before deploying the final build of an application, the developer should search all source files for instances of the identifier UnderConstructionException to be sure that application is indeed complete.

Since:

1997

Version:

1999.04.19

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
UnderConstructionException() Initializes without detail.
UnderConstructionException(String iMessage) Initializes with detail.
UnderConstructionException(String iMessage, Throwable iCause) Initializes with detail and cause.
UnderConstructionException(Throwable iCause) Initializes with cause.

Method Summary

Methods inherited from class com.sharkysoft.fig.extra.dev.NotImplementedException

trace, trace

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

UnderConstructionException

public UnderConstructionException()

Initializes without detail.

Details: This default constructor initializes a new instance without a detail message.

UnderConstructionException

public UnderConstructionException(String iMessage)

Initializes with detail.

Details: This constructor initializes a new instance with the given detail message.

Parameters:

iMessage - the messsage

UnderConstructionException

public UnderConstructionException(String iMessage,
                          Throwable iCause)

Initializes with detail and cause.

Details: This constructor initializes a new instance with the given detail message and wraps the exception that caused the VM to reach the unimplemented execution path.

This constructor may be useful for marking unimplemented execution paths in catch blocks.

Parameters:

iMessage - the message

iCause - the causing exception

UnderConstructionException

public UnderConstructionException(Throwable iCause)

Initializes with cause.

Details: This constructor wraps the exception that caused the VM to reach the unimplemented execution path.

This constructor may be useful for marking unimplemented execution paths in catch blocks.

Parameters:

iCause - the causing exception