tsp, design discussion, client hierarchy

[weidongxu-microsoft]

see https://github.com/Azure/typespec-azure-pr/issues/3809#discussion_r1405948920

Should Java support nested client?
E.g. petStoreClient.getPets().getActions().feed()

[weidongxu-microsoft]

petStoreClientBuilder.buildPets()
petStoreClientBuilder.buildPetsActions()

[weidongxu-microsoft]

petStoreClientBuilder.buildPets()
petStoreClientBuilder.<other-configures>.pets().buildActions()

[weidongxu-microsoft]

Scenario for Face AI (with client parameter)

getClient pattern

We currently have this pattern (only?) in storage-blob.

FaceServiceClient faceServiceClient = new FaceServiceClientBuilder().buildClient();
FaceListClient faceListClient = faceServiceClient.getFaceListClient(faceListId);
// other clients
PersonGroupClient otherClient = faceServiceClient.getPersonGroupClient();

(PS: in current client.tsp, FaceServiceClient contains no API, only operation groups -- hence it won't be generated in Java)

buildClient pattern

FaceListClient faceListClient = new FaceServiceClientBuilder()
    .faceListId(faceListId)
    .buildFaceListClient();
// other clients
PersonGroupClient otherClient = new FaceServiceClientBuilder()
    .buildPersonGroupClient();

Some verification logic is needed in Builder, to verify that faceListId is provided when creating FaceListClient.

A minor variation

Use a dedicated builder for FaceListClient, so that it be clearer no faceListId is settable to other clients.

FaceListClient faceListClient = new FaceListClientBuilder()
    .faceListId(faceListId)
    .buildClient();
// other clients
PersonGroupClient otherClient = new FaceServiceClientBuilder()
    .buildPersonGroupClient();

[weidongxu-microsoft]

Known namespace/interface patterns (assume namespace/interface always contains some operations)

// same to @client
// var client = new ClientBuilder().buildClient();
namespace Client {
}

// same to @client and @operationGropu
// var og1Client = new ClientBuilder().buildOg1Client();
namespace Client {
  interface Og1 {};
  interface Og2 {};
}

// intend to be
// var og1Client = new ClientBuilder().buildClient().getOg1Client(level1Options);
namespace Client {
  @clientInitialization(ClientLevel1Options)
  interface Og1 {};
  interface Og2 {};
}

// intend to be
// var og1Client = new ClientBuilder().buildClient().getClientLevel2().getClientLevel3().getOg1Client();
namespace Client {
  namespace ClientLevel2 {
    namespace ClientLevel3 {
      interface Og1 {};
      interface Og2 {};
    }
  }
}

// intent as
// var og1Client = new ClientBuilder().buildClient().getClientLevel2(level2Options).getClientLevel3(level3Options).getOg1Client(level4Options);
namespace Client {
  @clientInitialization(ClientLevel2Options)
  namespace ClientLevel2 {
    @clientInitialization(ClientLevel3Options)
    namespace ClientLevel3 {
      @clientInitialization(ClientLevel4Options)
      interface Og1 {};
      interface Og2 {};
    }
  }
}

All of these patterns can exist in a single tsp file.

---

Plan to use an emitter option (e.g. client-accessor or enable-subclient) to switch the client hierarchy pattern.

[weidongxu-microsoft]

ref Azure/typespec-azure#1702