tsp, internalApi generate model classes (#2300)

Author: weidongxu-microsoft

extension-base/src/main/java/com/azure/autorest/extension/base/model/codemodel/Operation.java

@@ -67,11 +67,10 @@ public class Operation extends Metadata {
 
     private ConvenienceApi convenienceApi;
 
-    /**
-     * a boolean to represent should generate protocol api or not, default is true
-     */
     private Boolean generateProtocolApi;
 
+    private Boolean internalApi;
+
     // internal
     private OperationGroup operationGroup;
 
@@ -292,4 +291,12 @@ public Boolean getGenerateProtocolApi() {
     public void setGenerateProtocolApi(Boolean generateProtocolApi) {
         this.generateProtocolApi = generateProtocolApi;
     }
+
+    public Boolean getInternalApi() {
+        return internalApi;
+    }
+
+    public void setInternalApi(Boolean internalApi) {
+        this.internalApi = internalApi;
+    }
 }

javagen/src/main/java/com/azure/autorest/mapper/ClientMethodMapper.java

@@ -296,11 +296,18 @@ private List<ClientMethod> createClientMethods(Operation operation, boolean isPr
                 final MethodOverloadType defaultOverloadType = hasNonRequiredParameters(parameters) ? MethodOverloadType.OVERLOAD_MAXIMUM : MethodOverloadType.OVERLOAD_MINIMUM_MAXIMUM;
                 final boolean generateOnlyRequiredParameters = settings.isRequiredParameterClientMethods() && defaultOverloadType == MethodOverloadType.OVERLOAD_MAXIMUM;
 
+                JavaVisibility methodVisibilityInWrapperClient = JavaVisibility.Public;
+                if ((isProtocolMethod && operation.getGenerateProtocolApi() == Boolean.FALSE)
+                        || (!isProtocolMethod && operation.getInternalApi() == Boolean.TRUE)) {
+                    // Client method is package private in wrapper client, so that the client or developer can still invoke it.
+                    methodVisibilityInWrapperClient = JavaVisibility.PackagePrivate;
+                }
+
                 builder.parameters(parameters)
                     .requiredNullableParameterExpressions(requiredParameterExpressions)
                     .validateExpressions(validateExpressions)
                     .methodTransformationDetails(methodTransformationDetails)
-                    .methodVisibilityInWrapperClient(isProtocolMethod && operation.getGenerateProtocolApi() == Boolean.FALSE ? JavaVisibility.PackagePrivate : JavaVisibility.Public)
+                    .methodVisibilityInWrapperClient(methodVisibilityInWrapperClient)
                     .methodPageDetails(null);
 
                 if (isPageable) {

javagen/src/main/java/com/azure/autorest/template/ConvenienceMethodTemplateBase.java

@@ -68,9 +68,11 @@ public void write(ConvenienceMethod convenienceMethodObj, JavaClass classBlock,
                     addGeneratedAnnotation(classBlock);
                     TemplateUtil.writeClientMethodServiceMethodAnnotation(convenienceMethod, classBlock);
 
+                    JavaVisibility methodVisibility = convenienceMethod.getMethodVisibilityInWrapperClient();
+
                     // convenience method
                     String methodDeclaration = String.format("%1$s %2$s(%3$s)", convenienceMethod.getReturnValue().getType(), getMethodName(convenienceMethod), convenienceMethod.getParametersDeclaration());
-                    classBlock.publicMethod(methodDeclaration, methodBlock -> {
+                    classBlock.method(methodVisibility, null, methodDeclaration, methodBlock -> {
                         methodBlock.line("// Generated convenience method for " + getMethodName(protocolMethod));
 
                         writeMethodImplementation(protocolMethod, convenienceMethod, methodBlock, typeReferenceStaticClasses);

package.json

@@ -40,6 +40,7 @@
   ],
   "devDependencies": {
     "autorest": "^3.0.0",
-    "@microsoft.azure/autorest.testserver": "3.3.45"
+    "@microsoft.azure/autorest.testserver": "3.3.45",
+    "functions-have-names": "~1.2.3"
   }
 }

typespec-extension/changelog.md

@@ -1,5 +1,12 @@
 # Release History
 
+## 0.8.13 (Unreleased)
+
+Compatible with compiler 0.48.
+
+- Supported `@include` from typespec-client-generator-core.
+- Supported generate model classes to implementation package, for API of `@access(Access.internal)` or `@internal`.
+
 ## 0.8.12 (2023-09-12)
 
 Compatible with compiler 0.47.

typespec-extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-java",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "TypeSpec library for emitting Java client from the TypeSpec REST protocol binding",
   "keywords": [
     "TypeSpec"
@@ -58,18 +58,18 @@
     "js-yaml": "~4.1.0"
   },
   "devDependencies": {
-    "@types/lodash": "~4.14.196",
+    "@types/lodash": "~4.14.198",
     "@types/js-yaml": "~4.0.5",
     "@types/mocha": "~10.0.1",
-    "@types/node": "~20.4.9",
+    "@types/node": "~20.6.0",
     "@types/prettier": "~2.7.3",
     "c8": "~8.0.1",
-    "eslint": "~8.46.0",
+    "eslint": "~8.49.0",
     "mocha": "~10.2.0",
     "rimraf": "~5.0.1",
-    "typescript": "~5.1.6",
-    "@typescript-eslint/parser": "~6.3.0",
-    "@typescript-eslint/eslint-plugin": "~6.3.0",
+    "typescript": "~5.2.2",
+    "@typescript-eslint/parser": "~6.7.0",
+    "@typescript-eslint/eslint-plugin": "~6.7.0",
     "eslint-plugin-deprecation": "~1.5.0"
   }
 }

typespec-extension/src/code-model-builder.ts

@@ -68,6 +68,7 @@ import {
   shouldGenerateProtocol,
   isInternal,
   SdkClient,
+  isInclude,
 } from "@azure-tools/typespec-client-generator-core";
 import { fail } from "assert";
 import {
@@ -366,7 +367,7 @@ export class CodeModelBuilder {
     if (access) {
       return access === "internal";
     } else {
-      // fallback to "internal", it will be
+      // TODO: deprecate "internal"
       return isInternal(context, operation);
     }
   }
@@ -377,31 +378,39 @@ export class CodeModelBuilder {
       const models: (Model | Enum)[] = Array.from(client.service.models.values());
       Array.from(client.service.enums.values()).forEach((it) => models.push(it));
 
+      // lambda to mark model as public
+      const modelAsPublic = (model: Model | Enum) => {
+        // check it does not contain Union
+        const union = unionReferredByType(this.program, model, this.typeUnionRefCache);
+        if (union) {
+          const errorMsg = `Model '${getTypeName(
+            model,
+            this.typeNameOptions,
+          )}' cannot be set as access=public, as it refers Union '${getUnionName(union, this.typeNameOptions)}'`;
+          throw new Error(errorMsg);
+        }
+
+        const schema = this.processSchema(model, model.name);
+
+        this.trackSchemaUsage(schema, {
+          usage: [SchemaContext.Public],
+        });
+      };
+
       for (const model of models) {
         if (!processedModels.has(model)) {
           const access = getAccess(model);
           if (access === "public") {
-            // check it does not contain Union
-            const union = unionReferredByType(this.program, model, this.typeUnionRefCache);
-            if (union) {
-              const errorMsg = `Model '${getTypeName(
-                model,
-                this.typeNameOptions,
-              )}' cannot be set as access=public, as it refers Union '${getUnionName(union, this.typeNameOptions)}'`;
-              throw new Error(errorMsg);
-            }
-
-            const schema = this.processSchema(model, model.name);
-
-            this.trackSchemaUsage(schema, {
-              usage: [SchemaContext.Public],
-            });
+            modelAsPublic(model);
           } else if (access === "internal") {
             const schema = this.processSchema(model, model.name);
 
             this.trackSchemaUsage(schema, {
               usage: [SchemaContext.Internal],
             });
+          } else if (model.kind === "Model" && isInclude(this.sdkContext, model)) {
+            // TODO: deprecate "include"
+            modelAsPublic(model);
           }
 
           const usage = getUsage(model);
@@ -596,12 +605,10 @@ export class CodeModelBuilder {
       },
     });
 
-    // TODO (weidxu): temporary disable codeModelOperation.internalApi
-    // codeModelOperation.internalApi = this.isInternal(this.sdkContext, operation);
-    const internalApi = this.isInternal(this.sdkContext, operation);
+    codeModelOperation.internalApi = this.isInternal(this.sdkContext, operation);
 
     const convenienceApiName = this.getConvenienceApiName(operation);
-    let generateConvenienceApi: boolean = !!convenienceApiName && !internalApi; // at present, internalApi means not convenienceApi. this could change.
+    let generateConvenienceApi: boolean = !!convenienceApiName;
 
     let apiComment: string | undefined = undefined;
     if (generateConvenienceApi) {
@@ -1259,7 +1266,12 @@ export class CodeModelBuilder {
             );
           });
 
-          this.trackSchemaUsage(optionBagSchema, { usage: [SchemaContext.Input, SchemaContext.Public] });
+          this.trackSchemaUsage(optionBagSchema, { usage: [SchemaContext.Input] });
+          if (op.internalApi) {
+            this.trackSchemaUsage(optionBagSchema, { usage: [SchemaContext.Internal] });
+          } else if (op.convenienceApi) {
+            this.trackSchemaUsage(optionBagSchema, { usage: [SchemaContext.Public] });
+          }
 
           // option bag parameter
           const optionBagParameter = new Parameter(

typespec-tests/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "typespec-java-tests",
+  "name": "@azure-tools/typespec-java-tests",
   "version": "0.0.1",
   "type": "module",
   "scripts": {
@@ -9,23 +9,24 @@
     "testserver-run": "npx cadl-ranch serve ./node_modules/@azure-tools/cadl-ranch-specs/http --coverageFile ./cadl-ranch-coverage-java.json"
   },
   "dependencies": {
-    "@typespec/openapi": ">=0.45.0 <1.0.0",
-    "@azure-tools/typespec-autorest": ">=0.31.0 <1.0.0",
-    "@azure-tools/cadl-ranch-specs": "0.21.0",
-    "@azure-tools/typespec-java": "file:/../typespec-extension/azure-tools-typespec-java-0.8.12.tgz"
+    "@typespec/openapi": ">=0.48.0 <1.0.0",
+    "@azure-tools/typespec-autorest": ">=0.34.0 <1.0.0",
+    "@azure-tools/cadl-ranch-specs": "0.22.0",
+    "@azure-tools/typespec-java": "file:/../typespec-extension/azure-tools-typespec-java-0.8.13.tgz"
   },
   "devDependencies": {
-    "@typespec/prettier-plugin-typespec": ">=0.45.0 <1.0.0",
+    "@typespec/prettier-plugin-typespec": "~0.48.0",
     "prettier-plugin-organize-imports": "3.2.3",
-    "prettier": "~3.0.1"
+    "prettier": "~3.0.3",
+    "functions-have-names": "~1.2.3"
   },
   "overrides": {
-    "@typespec/compiler": ">=0.45.0 <1.0.0",
-    "@typespec/http": ">=0.45.0 <1.0.0",
-    "@typespec/rest": ">=0.45.0 <1.0.0",
-    "@typespec/versioning": ">=0.45.0 <1.0.0",
-    "@azure-tools/typespec-azure-core": ">=0.31.0 <1.0.0",
-    "@azure-tools/typespec-client-generator-core": "0.34.0-dev.6"
+    "@typespec/compiler": ">=0.48.0 <1.0.0",
+    "@typespec/http": ">=0.48.0 <1.0.0",
+    "@typespec/rest": ">=0.48.0 <1.0.0",
+    "@typespec/versioning": ">=0.48.0 <1.0.0",
+    "@azure-tools/typespec-azure-core": ">=0.34.0 <1.0.0",
+    "@azure-tools/typespec-client-generator-core": ">=0.34.0 <1.0.0"
   },
   "private": true
 }

typespec-tests/src/main/java/com/_specs_/azure/clientgenerator/core/access/InternalOperationAsyncClient.java

@@ -5,6 +5,9 @@
 package com._specs_.azure.clientgenerator.core.access;
 
 import com._specs_.azure.clientgenerator.core.access.implementation.InternalOperationsImpl;
+import com._specs_.azure.clientgenerator.core.access.implementation.models.InternalDecoratorModelInInternal;
+import com._specs_.azure.clientgenerator.core.access.implementation.models.NoDecoratorModelInInternal;
+import com._specs_.azure.clientgenerator.core.access.implementation.models.PublicDecoratorModelInInternal;
 import com.azure.core.annotation.Generated;
 import com.azure.core.annotation.ReturnType;
 import com.azure.core.annotation.ServiceClient;
@@ -16,6 +19,7 @@
 import com.azure.core.http.rest.RequestOptions;
 import com.azure.core.http.rest.Response;
 import com.azure.core.util.BinaryData;
+import com.azure.core.util.FluxUtil;
 import reactor.core.publisher.Mono;
 
 /** Initializes a new instance of the asynchronous AccessClient type. */
@@ -110,4 +114,73 @@ Mono<Response<BinaryData>> internalDecoratorInInternalWithResponse(String name,
     Mono<Response<BinaryData>> publicDecoratorInInternalWithResponse(String name, RequestOptions requestOptions) {
         return this.serviceClient.publicDecoratorInInternalWithResponseAsync(name, requestOptions);
     }
+
+    /**
+     * The noDecoratorInInternal operation.
+     *
+     * @param name A sequence of textual characters.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws ClientAuthenticationException thrown if the request is rejected by server on status code 401.
+     * @throws ResourceNotFoundException thrown if the request is rejected by server on status code 404.
+     * @throws ResourceModifiedException thrown if the request is rejected by server on status code 409.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return used in an internal operation, should be generated but not exported on successful completion of {@link
+     *     Mono}.
+     */
+    @Generated
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    Mono<NoDecoratorModelInInternal> noDecoratorInInternal(String name) {
+        // Generated convenience method for noDecoratorInInternalWithResponse
+        RequestOptions requestOptions = new RequestOptions();
+        return noDecoratorInInternalWithResponse(name, requestOptions)
+                .flatMap(FluxUtil::toMono)
+                .map(protocolMethodData -> protocolMethodData.toObject(NoDecoratorModelInInternal.class));
+    }
+
+    /**
+     * The internalDecoratorInInternal operation.
+     *
+     * @param name A sequence of textual characters.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws ClientAuthenticationException thrown if the request is rejected by server on status code 401.
+     * @throws ResourceNotFoundException thrown if the request is rejected by server on status code 404.
+     * @throws ResourceModifiedException thrown if the request is rejected by server on status code 409.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return used in an internal operation, should be generated but not exported on successful completion of {@link
+     *     Mono}.
+     */
+    @Generated
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    Mono<InternalDecoratorModelInInternal> internalDecoratorInInternal(String name) {
+        // Generated convenience method for internalDecoratorInInternalWithResponse
+        RequestOptions requestOptions = new RequestOptions();
+        return internalDecoratorInInternalWithResponse(name, requestOptions)
+                .flatMap(FluxUtil::toMono)
+                .map(protocolMethodData -> protocolMethodData.toObject(InternalDecoratorModelInInternal.class));
+    }
+
+    /**
+     * The publicDecoratorInInternal operation.
+     *
+     * @param name A sequence of textual characters.
+     * @throws IllegalArgumentException thrown if parameters fail the validation.
+     * @throws HttpResponseException thrown if the request is rejected by server.
+     * @throws ClientAuthenticationException thrown if the request is rejected by server on status code 401.
+     * @throws ResourceNotFoundException thrown if the request is rejected by server on status code 404.
+     * @throws ResourceModifiedException thrown if the request is rejected by server on status code 409.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
+     * @return used in an internal operation but with public decorator, should be generated and exported on successful
+     *     completion of {@link Mono}.
+     */
+    @Generated
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    Mono<PublicDecoratorModelInInternal> publicDecoratorInInternal(String name) {
+        // Generated convenience method for publicDecoratorInInternalWithResponse
+        RequestOptions requestOptions = new RequestOptions();
+        return publicDecoratorInInternalWithResponse(name, requestOptions)
+                .flatMap(FluxUtil::toMono)
+                .map(protocolMethodData -> protocolMethodData.toObject(PublicDecoratorModelInInternal.class));
+    }
 }