Error Handling in the Java API

[mbwhite]

Hello - I wanted to start a discussion based around the error handling - in this case specifically the Java Gateway - but applicable across the other languages.

Here for example is the Java code used to submit a transaction. Catching Throwable I know is an 'anti-pattern'

        try (Gateway gateway = builder.connect()) {

            Network network = gateway.getNetwork(networkChannel);
            Contract contract = network.getContract(contractName);

            Jsonb jsonb = JsonbBuilder.create();
            String json = jsonb.toJson(le);

            LOGGER.info("submit:" + json);
            contract.submitTransaction("create", json);
        } catch (Throwable e) {
            LOGGER.severe("Failed to submit transaction " + e.getMessage());
            Quarkus.asyncExit();
            processException(e);
            throw new RuntimeException(e);
        }

This is being called within the Quarkus framework in response to requests arriving from a messaging system via JMS Transacted Context. This means that any failures will result in the request being returned and not lost.

Issue is what is the best approach to catching and handling errors within the the above code? The types of errors that could occur....

• NullPointer or similar - the JVM is 'giving up completely' or something very fundamental has gone wrong. Very little I could do here accept try and shutdown as cleanly as possible
• There's a networking or similar transient error case. Here we probably want to retry at a later date, but don't want to shut down this whole JVM
• Application-level errors that come from the contract... maybe this could be 'record already exists'. This is an error but at an application layer, so this specific request should fail, but shouldn't affect anything else.

Not sure that today, the API let's us handle these three cases very differently....

[bestbeforetoday]

You're right, the different distinct error cases are not well enough distinguished by the errors returned right now. More work is planned here.

You can get better information on the part of the submit flow where an error occurs by using the finer grained invocation flow in the API, which for Java would be something like:

Proposal proposal = contract.newProposal("create")
        .addArguments(jsonArg)
        .build();
        
// If required, transaction ID is available before the proposal is sent for endorsement
String transactionId = proposal.getTransactionId();

Transaction transaction = proposal.endorse();

// If required, result is available immediately after endorsement
byte[] result = transaction.getResult();

// Submit to orderer and return immediately so you can wait asynchronously for commit confirmation
SubmittedTransaction submittedTx = transaction.submitAsync();

if (!submittedTx.isSuccessful()) {
    TransactionPackage.TxValidationCode status = submittedTx.getStatus();
    // Choose action based on reason for commit failure
}

// For convenience, result is also available after submit
result = submittedTx.getResult();

The gRPC exceptions thrown are still not as helpful as they should be, but you can handle exceptions generated at any point during that flow and know at which step things went wrong.

Until the point you have a SubmittedTransaction you haven't delivered anything to the orderer, so the ledger is unchanged. After that point you need to either:

1. React based on the transaction commit status; or
2. Give up waiting for the commit status, assume it was lost after delivery to the orderer, and call submit again.

There is also an open high-level question on whether checked or unchecked exceptions are preferred for application developers. As I write this, the API throws unchecked io.grpc.StatusRuntimeException, but we could easily convert these into checked equivalents.