Module com.blackhillsoftware.zutil
Package com.blackhillsoftware.zutil.mvs

Class CommandHandler

java.lang.Object
com.blackhillsoftware.zutil.mvs.CommandHandler
public class CommandHandler extends Object
Wrapper for the com.ibm.jzos.MvsCommandCallback interface allowing multiple command handlers to be defined from multiple classes.

Users of this class can provide functions to be called for the JZOS MvsCommandCallback.handleModify(String), MvsCommandCallback.handleStop() and MvsCommandCallback.handleStart(String) events.

Multiple Command Handlers

Multiple CommandHandlers can be registered for each function. onStart(Consumer<String>) functions will be called immediately if START arguments are available. onModify(Function<String, Boolean>) and onStop(BooleanSupplier) will be called in order of last registered to first registered.

If there is an existing com.ibm.jzos.MvsCommandCallback registered, it will be called last, after any CommandHandler routines.

The onModify(Function<String, Boolean>) functions return a boolean value to indicate whether they handled the MODIFY command i.e. it was a command directed to that routine. If an onModify(Function<String, Boolean>) routine returns true, the remaining routines will not be called.

Note: This class will save any existing MvsCommandCallback and call it after the functions defined here. Other implementations of com.ibm.jzos.MvsCommandCallback may not be coded to allow multiple call-back functions. If they register a MvsCommandCallback after this CommandHandler is established, call-backs to this class may not be processed.

MVS STOP command and System.exit()

JZOS MvsCommandCallback.handleStop() specifies that if the function returns true, JZOS will call System.exit(0). CommandHandler will call all the defined onStop routines, and if any return true, CommandHandler will return true to JZOS after calling the last routine.

Note: System.exit(0) generally results in an untidy end of the Java program. It is better to return false from the onStop routine and end the program using normal return statements or throwing an exception, to allow files to be closed etc.

Example

Set up a function to process MODIFY commands: 
 
 public class ConsoleApp {
 
     public static void main(String[] args) {
        CommandHandler.onModify(ConsoleApp::handleModify);
     }
 
     private static boolean handleModify(String command) {
        if (command.equals("HELLO")) {
            System.out.println("Hello");
            return true; // handled
        }
        return false;
     }
 }

  • Method Details

    • onStart

      public static void onStart(Consumer<String> onStartFunction)
      Provide a function to receive the arguments to the START command. As for MvsCommandCallback.handleStart(String) the method will fire immediately because the START command has already been issued.

      As the method fires immediately, it is not saved so there is no corresponding removeStart() function.

      Parameters:
      onStartFunction - the routine to receive the START parameters

    • onModify

      public static CommandHandler onModify(Function<String,Boolean> onModifyFunction)
      Provide a function to handle MVS MODIFY commands. Due to the quirks of JZOS, MODIFY commands need to be of the form 
       MODIFY jobname,APPL=command
      where "command" is the string received by this routine.

      Multiple onModify routines can be provided to handle different commands. The routine can indicate by the return value whether it recognized and handled the MODIFY command, or whether it should be passed to the next routine in turn.

      The onModify routine should return true if the routine has handled the MODIFY command and no more onModify routines should be called, or false if the routine did not handle the command and it should be passed to the next function.

      Parameters:
      onModifyFunction - the routine to receive the MODIFY command
      Returns:
      the CommandHandler for the onModify routine, which can be saved and used to remove the routine via removeModify(CommandHandler) if required.

    • onStop

      public static CommandHandler onStop(BooleanSupplier onStopFunction)
      Provide a function to be called when a MVS STOP command is received.

      If the function returns true, this class will return "true" to JZOS to indicate that System.exit(0) should be called, after calling all onStop functions. All onStop functions will be called, if any return true System.exit(0) will then be called.

      Parameters:
      onStopFunction - the routine to call for the STOP command
      Returns:
      the CommandHandler for the onStop routine, which can be saved and used to remove the routine via removeStop(CommandHandler) if required.

    • removeModify

      public static boolean removeModify(CommandHandler onModifyHandler)
      Remove a command handler for MODIFY commands.
      Parameters:
      onModifyHandler - the CommandHandler returned by onModify(Function)
      Returns:
      true if the CommandHandler was found and removed.

    • removeStop

      public static boolean removeStop(CommandHandler onStopHandler)
      Remove a command handler for STOP commands.
      Parameters:
      onStopHandler - the CommandHandler returned by onStop(BooleanSupplier)
      Returns:
      true if the CommandHandler was found and removed.

    • removeAll

      public static void removeAll()
      Remove all command handlers added using this class. If there was already a MvsCommandCallback registered it will remain in place.