Tutorial - Tracing a Command Execution Path

To start the debugging session, simply Run > Debug Main

Enter edit 1 n/Alice Yeoh into the command box and press Enter.

The Debugger tool window should show up and look something like this:

Use the Show execution point feature to jump to the line of code that we stopped at:

CommandResult commandResult = logic.execute(commandText); is the line that you end up at.

We are interested in the logic.execute(commandText) portion of that line so let’s Step in into that method call:

We end up in LogicManager#execute(). Let’s take a look at the body of the method and annotate what we can deduce.

@Override
public CommandResult execute(String commandText) throws CommandException, ParseException {
     //Logging, safe to ignore
     logger.info("----------------[USER COMMAND][" + commandText + "]");

     CommandResult commandResult;
     //Parse user input from String to a Command
     Command command = addressBookParser.parseCommand(commandText);
     //Executes the Command and stores the result
     commandResult = command.execute(model);

     try {
         //We can deduce that the previous line of code modifies model in some way
         // since it's being stored here.
         storage.saveAddressBook(model.getAddressBook());
     } catch (IOException ioe) {
         throw new CommandException(FILE_OPS_ERROR_MESSAGE + ioe, ioe);
     }

     return commandResult;
 }

LogicManager#execute() appears to delegate most of the heavy lifting to other components. Let’s take a closer look at each one.

Step over the logging code since it is of no interest to us now.

Step into the line where user input in parsed from a String to a Command.

public Command parseCommand(String userInput) throws ParseException {
    ...
    final String commandWord = matcher.group("commandWord");
    final String arguments = matcher.group("arguments");
    ...

Step over until you reach the switch statement. The Variables window now shows the value of both commandWord and arguments :

We see that the value of commandWord is now edit but arguments is still not processed in any meaningful way.

Stepping into the switch, we obviously stop at

...
case EditCommand.COMMAND_WORD:
    return new EditCommandParser().parse(arguments);
...

Let’s see what EditCommandParser#parse() does by stepping into it.

Stepping through the method shows that it calls ArgumentTokenizer#tokenize() and ParserUtil#parseIndex() to obtain the arguments and index required.

The rest of the method seems to exhaustively check for the existence of each possible parameter of the edit command and store any possible changes in an EditPersonDescriptor. Recall that we can verify the contents of editPersonDesciptor through the Variable tool window.

Let’s continue stepping through until we return to LogicManager#execute().

Figure 4. Tracing an edit command through the Logic component

Now let’s see what happens when we call command#execute()!

@Override
public CommandResult execute(Model model) throws CommandException {
    ...
    Person personToEdit = lastShownList.get(index.getZeroBased());
    Person editedPerson = createEditedPerson(personToEdit, editPersonDescriptor);
    if (!personToEdit.isSamePerson(editedPerson) && model.hasPerson(editedPerson)) {
        throw new CommandException(MESSAGE_DUPLICATE_PERSON);
    }
    model.setPerson(personToEdit, editedPerson);
    model.updateFilteredPersonList(PREDICATE_SHOW_ALL_PERSONS);
    return new CommandResult(String.format(MESSAGE_EDIT_PERSON_SUCCESS, editedPerson));
}

As suspected, command#execute() does indeed make changes to model.

We can a closer look at how storage works by repeatedly stepping into the code until we arrive at JsonAddressBook#saveAddressBook().

Again, it appears that the heavy lifting is delegated. Let’s take a look at JsonSerializableAddressBook's constructor.

/**
 * Converts a given {@code ReadOnlyAddressBook} into this class for Jackson use.
 *
 * @param source future changes to this will not affect the created
 * {@code JsonSerializableAddressBook}.
 */
public JsonSerializableAddressBook(ReadOnlyAddressBook source) {
    persons.addAll(
        source.getPersonList()
              .stream()
              .map(JsonAdaptedPerson::new)
              .collect(Collectors.toList()));
}

It appears that a JsonAdaptedPerson is created for each Person and then added to the JsonSerializableAddressBook.

We can continue to step through until we return to MainWindow#executeCommand().

Stepping into resultDisplay.setFeedbackToUser(commandResult.getFeedbackToUser());, we end up in:

public void setFeedbackToUser(String feedbackToUser) {
    requireNonNull(feedbackToUser);
    resultDisplay.setText(feedbackToUser);
}

Finally, we step through until we reach the end of MainWindow#executeCommand().