Perform multiple operations and commit

Question

A system handles two types of resources. There are write and delete APIs for managing the resources. A client (user) will use a library API to manage these resources. Each resource write (or create) will result in updating a store or a database.

The API would look like:

1) Create Library client. The user will use the returned client to operate on the resources.

MyClient createClient(); //to create the client

2) MyClient interface. Providing operations on a resource

writeResourceType1(id);
deleteResourceType1(id);

writeResourceType2(id);
deleteResourceType2(id);

Some resources are dependent on the other. The user may write them out-of-order (might write a resource before writing its dependent). In order to prevent the system from having an inconsistent state, all changes (resource updates) will be written to a staging location. The changes will be written to the actual store only when the user indicates he/she has written everything.

This means I would need a commit kind of method in the above MyClient interface. So, access pattern will look like

Client client = provider.createClient();
..
client.writeResourceType1(..)

client.writeResourceType1(..)

client.deleteResourceType2(..)

client.commit(); //<----

I'm not comfortable having the commit API in the MyClient interface. I feel it is polluting it and a wrong it is a wrong level of abstraction.

Is there a better way to handle this?

---

Another option I thought of is getting all the updates as part of a single call. This API would act as a Batch API

writeOrDelete(List<Operations> writeAndDeleteOpsForAllResources)

The downside of this is this the user has to combine all the operations on their end to call this. This is also stuffing too much into a single call. So, I'm not inclined to this approach.

Answer 1

While both ways that you've presented can be viable options, the thing is that at some point in time, the user must somehow say: "Ok, these are are my changes, take them all or leave them". This is exactly what commit is IMO. And this alone makes necessary some kind of call that must present in the API.

In the first approach that you've presented its obviously explicit, and is done with commit method. In the second approach its rather implicit and is determined by the content of the list that you pass into writeOrDelete method.

So in my understanding, commit must exist somehow, but the question is how do you make it less "annoying" :)

Here are couple of tricks:

Trick 1: Builder / DSL

interface MyBuilder {
   MyBuilder addResourceType1(id);
   MyBuilder addResourceType2(id);
   MyBuilder deleteResourceType1/2...();
   BatchRequest build();
}

interface MyClient {
   BatchExecutionResult executeBatchRequest(BatchRequest req);
}

This method is more or less like the second method, however it has a clear way of "adding resources". A single point of creation (pretty much like MyClient not, just I believe that eventually it will have more methods, so maybe its a good idea to separate. As you stated: "I'm not comfortable having the commit API in the MyClient interface. I feel it is polluting it and a wrong it is a wrong level of abstraction") Additional argument for this approach is that now you know that there is a builder and its an "abstraction to go" in your code that uses this, you don't have to think about passing a reference to the list, think about what happens if someone calls stuff like clear() on this list, and so on and so forth. The builder has a precisely defined API of what can be done.

In terms of creating the builder:

You can go with something like Static Utility class or even add a method to MyClient:

// option1

public class MyClientDSL {
   private MyClientDSL {}
   public static MyBuilder createBuilder();
}

// option 2
public interface MyClient {
    MyBuilder newBuilder();
}

References to this approach: JOOQ (they have DSL like this), OkHttp that have builders for Http Requests, Bodies and so forth (decoupled from the OkHttpClient itself).

Trick 2: Providing an execution code block

Now this can be tricky to implement depending on what kind of environment do you run in, but basically an idea is borrowed from Spring: In order to guarantee a transaction while working with databases they provide a special annotation @Transactional that while placed on the methods basically says: "everything inside the method is running in transaction, I'll commit it by myself so that the user won't deal with transactions/commits at all. I'll also roll back upon exception"

So in code it looks like:

class MyBusinessService {
       private MyClient myClient; // injected
         @Transactional
         public void doSomething() {
             myClient.addResourceType1();
             ...
             myClient.addResourceType2();
             ...  
         }
}

Under the hood they should maintain ThreadLocals to make this possible in multithreaded environment, but the point is that the API is clean. The method commit might exist but probably won't be used at the most of the cases, leaving alone the really sophisticated scenarios where the user might really "need" this fine-grained control.

If you use spring/ any other containter that manages your code, you can integrate it with spring (the technical way of doing this is out of scope of this question, but you get the idea).

If not, you can provide the most simplistic way of it:

public class MyClientCommitableBlock {

    public static <T> T executeInTransaction(CodeBlock<T> someBlock)
            builder) {

          MyBuilder builder = create...;
          T result = codeBlock(builder);
          // build the request, execute and commit
          return result;
      }
}

Here is how it looks:

static import MyClientCommitableBlock.*;
public static void main() {

     Integer result = executeInTransaction(builder -> {
        builder.addResourceType1();
        ... 
        return 42;
     });
}

// or using method reference:

    class Bar {
       Integer foo() {
         return executeInTransaction(this::bar);    
       } 

       private Integer bar(MyBuilder builder) {
         ....
       }
    }

In this approach a builder while still defining precisely a set of APIs might not have an "explicit" commit method exposed to the end user. Instead it can have some "package private" method to be used from within the MyClientCommitableBlock class