convenience methods

[Douglas Surber]

ADBA includes a fair number of convenience methods. These are methods that encapsulate common code patterns into default methods. DataSource.getConnection() is an obvious example.

As default methods these are all implemented by calling other interface methods. Clearly they aren’t necessary as the app can make the same sequence of calls. On the other hand their use will result in more compact and more readable code. Also, some of them handle some not so obvious behavior so that the programmer doesn’t have to think about it in the common use case. Again DataSource.getConnection is a good example; look at Connection.connect. A third benefit and honestly the original motivation for many of them is as documentation, how to use the API.

As a general notion, do these methods carry their weight? Are the benefits they provide worth whatever additional complexity they add? 

Here is a concrete example to consider. This is a method in Connection.

  public default CompletionStage<TransactionOutcome> 
        executeAsTransaction(BiConsumer<OperationGroup, Transaction> action) {
    OperationGroup grp = this.operationGroup();
    Transaction tran = this.transaction();
    action.accept(grp, tran);
    grp.submit();
    return this.commitMaybeRollback(tran); *
  }

Clearly this method is not strictly necessary. It is implemented entirely by calling other methods present in ADBA. Any application or framework can do exactly the same. On the other hand most applications and frameworks would make exactly the same sequence of calls so including this pattern in ADBA would be convenient. Finally, this provides an example of how to use ADBA to execute a transaction. This is actually the original motivation for creating this method.

ADBA is based on some relatively primitive concepts. In some cases there is quite a conceptual distance between those primitive concepts and what an application wants to do. It is easier to specify, understand, and implement just the primitive concepts but that leaves a conceptual gap to what the app needs; how to compose the primitives into useful actions. The various convenience methods bridge this gap without adding any specification or implementation complexity. IMO these convenience methods actually reduce the complexity by adding an executable specification of how the primitives work together to support a higher level abstraction.

Should we add executeAsTransaction? What about other convenience methods? Suggestions welcome.

Douglas


* Note: commitMaybeRollback has been corrected to return CompletionStage<TransactionOutcome> which is clearly what it should do.