com.sharkysoft.util
Class NotImplementedException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              com.sharkysoft.util.NotImplementedException

All Implemented Interfaces:

java.io.Serializable

public class NotImplementedException

extends java.lang.RuntimeException

Indicates an unfinished execution path.

Details: A NotImplementedException 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 a class without implementing any of it. To do this, simply include the statement

throw new NotImplementedException();

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 (bReadyToRock)
{ do_stuff();
  do_more_stuff();
}
else
  throw new NotImplementedException();
     

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 forget's he'll be reminded when it's needed.

Example 2:

public static float[] findPolynomialRoots(Polynomial ipPolynomial)
{ // 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 NotImplementedException();
}
     

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 NotImplementedException 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 ipEvent)
{ // We're safe doing nothing for now, but eventually we'll need to
  // implement this.
  NotImplementedException.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 a problem. Rather than stopping the show with an exception, the developer has decided to simply let NotImplementedException 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 "NotImplementedException" to be sure that application is indeed complete.

Since:

1997

Version:

1999.04.19

See Also:

Serialized Form

Constructor Summary

NotImplementedException()
Initializes without detail.

NotImplementedException(java.lang.String isDetail)
Initializes with detail.

Method Summary

static void	trace() Prints stack trace of unimplemented execution path.
static void	trace(java.lang.String isDetail) Prints stack trace of unimplemented execution path.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, 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

NotImplementedException

public NotImplementedException()

Initializes without detail.

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

NotImplementedException

public NotImplementedException(java.lang.String isDetail)

Initializes with detail.

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

Parameters:

isDetail - the messsage

Method Detail

trace

public static void trace(java.lang.String isDetail)

Prints stack trace of unimplemented execution path.

Details: trace instantiates a new NotImplementedException without throwing it, and then outputs its stack trace to System.err. This is useful for tracking unfinished code paths which must be allowed to operate, albeit temporarily, in their unfinished state. The provided detail message is included in the stack trace.

Parameters:

isDetail - detail message

Since:

1999.06.04

See Also:

trace()

trace

public static void trace()

Prints stack trace of unimplemented execution path.

Details: trace() is the same as trace(String), except that no detail message is used.

Since:

1999.06.04

See Also:

trace(String)