com.hdcookbook.grin
Class GrinXHelper

java.lang.Object
  extended by com.hdcookbook.grin.commands.Command
      extended by com.hdcookbook.grin.GrinXHelper
All Implemented Interfaces:
Node
Direct Known Subclasses:
SEGrinXHelper

public class GrinXHelper
extends Command
implements Node

This class has three distinct functions. It's mostly a helper class that acts as a superclass for code that gets generated in a GRIN show file, for the java_command structures and for instantiating GRIN extensions. This class is also used directly for some built-in GRIN commands. Doing this kind of functional overloading in one class definition is admittedly not very OO, but experimental data shows that classloading is a moderately expensive operation, so we do this overloading to optimize xlet start-up time.

To illustrate the different functions of this class, assume a show that defines a class called MenuShowCommands as the helper classname in the show file. The functions of GrinXHelper are:

For the built-in GRIN commands, the direct instances of GrinXHelper get instantiated "automatically" by the GRIN binary reader. The class GrinXHelper is registered as a built-in class, so that part "just works" -- it's represented by the integer constant GRINXHELPER_CMD_IDENTIFIER. For the MenuShowCommands instances, they're represented by the (interned) string that hold the fully-qualified classname of MenuShowCommands, which the binary reader feeds (once) into Class.forName() so that it can call newInstance().

To see how the java_command commands get compiled into the show's subclass of GrinXHelper, see com.hdcookbook.grin.SEShowCommands

Accessing Blu-ray Player Registers

One thing you might want to do in a java_command is access a player register. That's easy to do, and there's even support in GrinView to emulate the values of player registers, so you can do some testing of the control logic of your show on a PC. In a show file, you can do this by including a static data member of your command subclass, as defined in the java_generated_class section of your show file:
     XLET_ONLY [[
     private final static org.bluray.system.RegisterAccess
         registers = org.bluray.system.RegisterAccess.getInstance();
     ]]
     GRINVIEW_ONLY [[
     private final static com.hdcookbook.grin.test.bigjdk.BDRegisterEmulator
         registers = com.hdcookbook.grin.test.bigjdk.BDRegisterEmulator.getInstance();
     ]]
 
With that, your commands can have statements like "int angleNumber = registers.getPSR(3)" or "registers.setGPR(10, 42)".

A better pattern might be to divide your director into an abstract superclass, with two implementations of the subclass, one for GrinView and one for a real xlet. That way, the common director can have an abstract method like "getPSR(int)" that you implement for GrinView in terms of an array, or maybe in terms of BDRegisterEmulator. This same abstract director pattern can be used for other player functionality, too. This is a more powerful and general technique than GRINVIEW_ONLY and XLET_ONLY.

Author:
Bill Foote (http://jovial.com)

Field Summary
protected static int COMMAND_LIST
          The commandNumber for the GRIN internal list-of-commands command
protected  int commandNumber
           
static int MOUSE_CLICK
          The commandNumber for handling MOUSE_CLICK event
static int MOUSE_MOVE
          The commandNumber for handling MOUSE_MOVE event
protected static int SEGMENT_DONE
          The commandNumber for a segment_done command
protected  Command[] subCommands
           
protected static int SYNC_DISPLAY
          The commandNumber for a sync_display command
 
Fields inherited from class com.hdcookbook.grin.commands.Command
show
 
Constructor Summary
GrinXHelper(Show show)
           
 
Method Summary
 void execute()
          Execute the command.
 void execute(Show caller)
          Execute the command.
 Node getInstanceOf(Show show, int id)
          Instantiate an extension class.
 void readInstanceData(GrinDataInputStream in, int length)
          Reads in this node information from the binary file format.
protected  void runSubCommand(int num, Show caller)
          Run a sub-command.
 void setCommandNumber(int commandNumber)
          Sets the command number for this class when used as a command.
 void setCommandObject(java.lang.Object object)
          Sets the additional data for this class when used as a command.
 void setSubCommands(Command[] subCommands)
          Sets the sub-commands array for this class when used as a java_command.
 java.lang.String toString()
          Return a user-friendly string for this command for debugging purposes.
 
Methods inherited from class com.hdcookbook.grin.commands.Command
cloneIfNeeded, deferNextCommands
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

commandNumber

protected int commandNumber

subCommands

protected Command[] subCommands

SYNC_DISPLAY

protected static final int SYNC_DISPLAY
The commandNumber for a sync_display command

See Also:
Constant Field Values

SEGMENT_DONE

protected static final int SEGMENT_DONE
The commandNumber for a segment_done command

See Also:
Constant Field Values

COMMAND_LIST

protected static final int COMMAND_LIST
The commandNumber for the GRIN internal list-of-commands command

See Also:
Constant Field Values

MOUSE_MOVE

public static final int MOUSE_MOVE
The commandNumber for handling MOUSE_MOVE event

See Also:
Constant Field Values

MOUSE_CLICK

public static final int MOUSE_CLICK
The commandNumber for handling MOUSE_CLICK event

See Also:
Constant Field Values
Constructor Detail

GrinXHelper

public GrinXHelper(Show show)
Method Detail

setCommandNumber

public void setCommandNumber(int commandNumber)
Sets the command number for this class when used as a command. This should only be called as part of initializing this object.


setCommandObject

public void setCommandObject(java.lang.Object object)
Sets the additional data for this class when used as a command. This should only be called as part of initializing this object.


setSubCommands

public void setSubCommands(Command[] subCommands)
Sets the sub-commands array for this class when used as a java_command. This should only be called as part of initializing the object.


runSubCommand

protected void runSubCommand(int num,
                             Show caller)
Run a sub-command. This supports the GRIN_COMMAND_[[ ]] commands within a command body. This may only be called within the thread that is calling execute() on the parent command.

Parameters:
num - The numeric ID of the command to execute. This is automatically generated by the compiler.

readInstanceData

public void readInstanceData(GrinDataInputStream in,
                             int length)
                      throws java.io.IOException
Reads in this node information from the binary file format.

An implementation of this method is recommended to call in.readSuperClassData(this) as the first line of the method to read in information that is defined in the base class of this Node type.

This should only be called while initializing this object.

Specified by:
readInstanceData in interface Node
Parameters:
in - InputStream to read data from.
length - the number of bytes that this node's information occupies in the InputStream. The implementation of this method is expected to read exactly this number of bytes from the stream. This can be used for a debugging purpose.
Throws:
java.io.IOException - if error occurs.
See Also:
GrinDataInputStream.readSuperClassData(Feature), GrinDataInputStream.readSuperClassData(RCHandler), GrinDataInputStream.readSuperClassData(Segment), GrinDataInputStream.readSuperClassData(Command)

execute

public void execute(Show caller)
Execute the command. This method must be overridden in the show's subclass of GrinXHelper, and that override must not call this method. The implementation of this method in GrinXHelper executes some built-in GRIN commands.

Overrides:
execute in class Command
Parameters:
caller - The show that is executing this command. This might not be the same as the show this command was created under.

execute

public void execute()
Execute the command. This causes the command to take whatever action it was created to do.

Specified by:
execute in class Command

getInstanceOf

public Node getInstanceOf(Show show,
                          int id)
                   throws java.io.IOException
Instantiate an extension class. This method must be overridden by the show's sublcass of GrinXHelper.

Throws:
java.io.IOException

toString

public java.lang.String toString()
Return a user-friendly string for this command for debugging purposes.

Overrides:
toString in class Command