com.hdcookbook.grin.util
Class Debug

java.lang.Object
  com.hdcookbook.grin.util.Debug

public class Debug
extends java.lang.Object

Debugging support. It is expected that in a real project, the file Debug.java will be physically replaced with a different source code file that * implements the same public API. For a deploy build, it should * have ASSERT set false, and LEVEL set to 0. For a debug build, it will almost certainly send the debug output somewhere more useful than stderr/stdout.

Replacing a source file and re-building a library may be unfamiliar to some Java programmers, but C programmers will instantly recognize this as the assert.h idiom. This way of doing things has fallen out of favor for desktop programming, but it is this author's opinion that the efficiency gain from stripping out assertions and debug statements at compile time is worth it in an embedded environment like Blu-ray.

The GrinXlet application framework (in xlets/GrinXlet) does as is outlined here -- the GrinXlet build excludes the version of Debug.java you're reading now, and replaces it with either a debug version (that sends debug info to a special screen you can access via the remote control, and that you can telnet to the player to get), and a deploy version (that sets the constants so that the compiler strips out debug and assertions).

Some people like to solve this problem by having a build system that edits one or two key source files, to change the value of some key constants (like ASSERT and LEVEL in this class) depending on the build. That's a great technique too, but in any case you'll need to write your own version of Debug.java if you want to go that way.

Note that the GRIN library was written assuming that the deploy version of an xlet will be built with ASSERT set false and LEVEL set to 0. It contains many assertions, some of which are computationally expensive. Consider, for example, com.hdcookbook.grin.features.Group.java, which has an assertion that spans a couple of screens and creates a HashSet.

More discussion of this can be found in Issue 164

Author:

Bill Foote (http://jovial.com)

Field Summary

static boolean	ASSERT Variable to say that assertions are enabled.
static int	LEVEL Debug level.
static boolean	PROFILE Variable to say if time profiling is enabled.
static boolean	PROFILE_ANIMATION Variable to say if animation profiling is enabled.
static boolean	PROFILE_SETUP Variable to say if setup profiling is enabled.

Method Summary

static void	assertFail() Called on assertion failure.
static void	assertFail(java.lang.String msg) Called on assertion failure.
static void	println()
static void	println(java.lang.Object o)
static void	printStackTrace(java.lang.Throwable t) Print a stack trace to the debug log, if Debug.LEVEL > 0.

Methods inherited from class java.lang.Object

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

Field Detail

ASSERT

public static final boolean ASSERT

Variable to say that assertions are enabled. If set false, then javac should strip all assertions out of the generated code.

Usage:

     if (Debug.ASSERT && some condition that should be false) {
         Debug.println(something interesting);
     }
 

Note that JDK 1.4's assertion facility can't be used for Blu-Ray, since PBP 1.0 is based on JDK 1.3.

See Also:

Constant Field Values

LEVEL

public static final int LEVEL

Debug level. 2 = noisy, 1 = some debug, 0 = none. See the comments about setting this value in the class comments.

See Also:

Constant Field Values

PROFILE

public static final boolean PROFILE

Variable to say if time profiling is enabled. See the comments about setting this value in the class comments.

See Also:

Profile, Constant Field Values

PROFILE_ANIMATION

public static final boolean PROFILE_ANIMATION

Variable to say if animation profiling is enabled. See the comments about setting this value in the class comments.

See Also:

Profile, Constant Field Values

PROFILE_SETUP

public static final boolean PROFILE_SETUP

Variable to say if setup profiling is enabled. See the comments about setting this value in the class comments.

See Also:

Profile, Constant Field Values

Method Detail

println

public static void println()

println

public static void println(java.lang.Object o)

assertFail

public static void assertFail(java.lang.String msg)

Called on assertion failure. This is a useful during development: When you detect a condition that should be impossible, you can trigger an assertion failure. That means you've found a bug. When an assertion failure is detected, you basically want to shut everything down, so that the developer notices immediately, and sees the message.

assertFail

public static void assertFail()

Called on assertion failure. This is a useful during development: When you detect a condition that should be impossible, you can trigger an assertion failure. That means you've found a bug. When an assertion failure is detected, you basically want to shut everything down, so that the developer notices immediately, and sees the message.

printStackTrace

public static void printStackTrace(java.lang.Throwable t)

Print a stack trace to the debug log, if Debug.LEVEL > 0. Note that you can also easily use this for the equivalent of Thread.dumpStack() using this bit of code:

      try {
          throw new RuntimeException("STACK BACKTRACE");
      } catch (RuntimeException ex) {
                Debug.printStackTrace(ex);
      }