Documentation and Sample Fixes for Schema Registry (Azure#26703)

* Adding SchemaId sync file. Renaming old file to GetSchemaIdSampleAsync.

* Renaming GetSchemaSample.java to GetSchemaSampleAsync.

* Fix documentation on getSchemaId.

* Fixing documentation on samples.

* Adding RegisterSchemaSample and renaming async sample to RegisterSchemaSampleAsync.

* Updating README links.

* Update README and readme samples.

* Updating documentation for Client and clientbuilder.

Author: conniey

sdk/schemaregistry/azure-data-schemaregistry-apacheavro/README.md

@@ -52,7 +52,7 @@ with the Azure SDK, please include the `azure-identity` package:
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
-    <version>1.4.1</version>
+    <version>1.4.3</version>
 </dependency>
 ```
 
@@ -62,8 +62,10 @@ You will also need to [register a new AAD application][register_aad_app] and [gr
 ```java readme-sample-createSchemaRegistryAsyncClient
 TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
 
+// {schema-registry-endpoint} is the fully qualified namespace of the Event Hubs instance. It is usually
+// of the form "{your-namespace}.servicebus.windows.net"
 SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
-    .fullyQualifiedNamespace("{schema-registry-endpoint")
+    .fullyQualifiedNamespace("{your-event-hubs-namespace}.servicebus.windows.net")
     .credential(tokenCredential)
     .buildAsyncClient();
 ```

sdk/schemaregistry/azure-data-schemaregistry-apacheavro/src/samples/java/com/azure/data/schemaregistry/apacheavro/ReadmeSamples.java

@@ -28,8 +28,10 @@ public SchemaRegistryApacheAvroSerializer createAvroSchemaRegistrySerializer() {
         // BEGIN: readme-sample-createSchemaRegistryAsyncClient
         TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
 
+        // {schema-registry-endpoint} is the fully qualified namespace of the Event Hubs instance. It is usually
+        // of the form "{your-namespace}.servicebus.windows.net"
         SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
-            .fullyQualifiedNamespace("{schema-registry-endpoint")
+            .fullyQualifiedNamespace("{your-event-hubs-namespace}.servicebus.windows.net")
             .credential(tokenCredential)
             .buildAsyncClient();
         // END: readme-sample-createSchemaRegistryAsyncClient

sdk/schemaregistry/azure-data-schemaregistry/README.md

@@ -42,7 +42,7 @@ To use the [DefaultAzureCredential][DefaultAzureCredential] provider shown below
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
-    <version>1.4.1</version>
+    <version>1.4.3</version>
 </dependency>
 ```
 

sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java

@@ -148,7 +148,8 @@ public Response<SchemaRegistrySchema> getSchemaWithResponse(String schemaId, Con
     }
 
     /**
-     * Gets the schema properties associated with the given schema id.
+     * Gets schema properties for a schema with matching {@code groupName}, {@code name}, {@code schemaDefinition}, and
+     * {@code format}.
      *
      * @param groupName The schema group.
      * @param name The schema name.
@@ -169,7 +170,8 @@ public SchemaProperties getSchemaProperties(String groupName, String name, Strin
     }
 
     /**
-     * Gets the schema identifier associated with the given schema.
+     * Gets schema properties for a schema with matching {@code groupName}, {@code name}, {@code schemaDefinition}, and
+     * {@code format} along with its HTTP response.
      *
      * @param groupName The schema group.
      * @param name The schema name.

sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClientBuilder.java

@@ -118,7 +118,7 @@ public class SchemaRegistryClientBuilder {
     private ServiceVersion serviceVersion;
 
     /**
-     * Constructor for CachedSchemaRegistryClientBuilder.  Supplies client defaults.
+     * Constructor for SchemaRegistryClientBuilder. Supplies client defaults.
      */
     public SchemaRegistryClientBuilder() {
         this.httpLogOptions = new HttpLogOptions();

sdk/schemaregistry/azure-data-schemaregistry/src/samples/README.md

@@ -22,8 +22,12 @@ Please refer to the [Getting Started][sdk_readme_getting_started] section.
 
 ## Examples
 
-- [Serialize an object into avro schema bytes][sample_avro_serialization]
-- [Deserialize avro serialized bytes into a strongly-typed object][sample_avro_deserialization]
+- [Register a schema][sample_register_schema]
+- [Register a schema using async client][sample_register_schema_async]
+- [Get schema][sample_get_schema]
+- [Get schema using async client][sample_get_schema_async]
+- [Get schema id][sample_get_schema_id]
+- [Get schema id using async client][sample_get_schema_id_async]
 
 ## Troubleshooting
 See [Troubleshooting][sdk_readme_troubleshooting].
@@ -40,8 +44,11 @@ This project welcomes contributions and suggestions. See [Contributing][sdk_read
 [sdk_readme_troubleshooting]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/README.md#troubleshooting
 [sdk_readme_next_steps]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/README.md#next-steps
 [sdk_readme_contributing]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/README.md#contributing
-[sample_register_schema]: ./java/com/azure/data/schemaregistry/RegisterSchemaSample.java
-[sample_get_schema]: ./java/com/azure/data/schemaregistry/GetSchemaSample.java
-[sample_get_schema_id]: ./java/com/azure/data/schemaregistry/GetSchemaIdSample.java
+[sample_register_schema]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSample.java
+[sample_register_schema_async]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSampleAsync.java
+[sample_get_schema]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSample.java
+[sample_get_schema_async]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSampleAsync.java
+[sample_get_schema_id]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java
+[sample_get_schema_id_async]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSampleAsync.java
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%schemaregistry%2Fazure-data-schemaregistry%2Fsrc%2Fsamples%2README.png)

sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java

@@ -5,38 +5,32 @@
 
 import com.azure.core.credential.TokenCredential;
 import com.azure.data.schemaregistry.models.SchemaFormat;
+import com.azure.data.schemaregistry.models.SchemaProperties;
 import com.azure.identity.DefaultAzureCredentialBuilder;
 
-import java.util.concurrent.CountDownLatch;
-
 /**
- * Sample to demonstrate retrieving the schema id of a schema from Schema Registry.
+ * Sample to demonstrate retrieving properties of a schema from Schema Registry.
+ *
+ * @see GetSchemaIdSampleAsync for the async sample.
  */
 public class GetSchemaIdSample {
 
     /**
      * The main method to run this program.
      * @param args Ignored args.
      */
-    public static void main(String[] args) throws InterruptedException {
+    public static void main(String[] args) {
         TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
 
-        SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
+        SchemaRegistryClient schemaRegistryClient = new SchemaRegistryClientBuilder()
             .fullyQualifiedNamespace("{schema-registry-endpoint")
             .credential(tokenCredential)
-            .buildAsyncClient();
-
-        CountDownLatch countDownLatch = new CountDownLatch(1);
-        // Register a schema
-        schemaRegistryAsyncClient
-            .getSchemaProperties("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO)
-            .subscribe(schemaId -> {
-                System.out.println("Successfully retrieved the schema id: " + schemaId);
-                countDownLatch.countDown();
-            });
+            .buildClient();
 
-        // wait for the async task to complete
-        countDownLatch.await();
+        // Gets the properties of an existing schema.
+        SchemaProperties schemaProperties = schemaRegistryClient
+            .getSchemaProperties("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO);
 
+        System.out.println("Successfully retrieved the schema id: " + schemaProperties.getId());
     }
 }

sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSampleAsync.java

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.data.schemaregistry;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.data.schemaregistry.models.SchemaFormat;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+import java.util.concurrent.CountDownLatch;
+
+/**
+ * Sample to demonstrate retrieving properties of a schema from Schema Registry using async client.
+ *
+ * @see GetSchemaIdSample for the synchronous sample.
+ */
+public class GetSchemaIdSampleAsync {
+
+    /**
+     * The main method to run this program.
+     * @param args Ignored args.
+     */
+    public static void main(String[] args) throws InterruptedException {
+        TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
+
+        SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
+            .fullyQualifiedNamespace("{schema-registry-endpoint")
+            .credential(tokenCredential)
+            .buildAsyncClient();
+
+        CountDownLatch countDownLatch = new CountDownLatch(1);
+
+        // Gets the properties of an existing schema.
+        // `subscribe` is a non-blocking operation. It hooks up the callbacks and then moves onto the next line of code.
+        schemaRegistryAsyncClient
+            .getSchemaProperties("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO)
+            .subscribe(schemaId -> {
+                System.out.println("Successfully retrieved the schema id: " + schemaId);
+                countDownLatch.countDown();
+            });
+
+        // wait for the async task to complete
+        countDownLatch.await();
+    }
+}

sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSample.java

@@ -4,38 +4,31 @@
 package com.azure.data.schemaregistry;
 
 import com.azure.core.credential.TokenCredential;
+import com.azure.data.schemaregistry.models.SchemaRegistrySchema;
 import com.azure.identity.DefaultAzureCredentialBuilder;
 
-import java.util.concurrent.CountDownLatch;
-
 /**
- * Sample to demonstrate retrieving a schema from Schema Registry.
+ * Sample to demonstrate retrieving a schema from Schema Registry using the sync client.
  */
 public class GetSchemaSample {
     /**
      * The main method to run this program.
+     *
      * @param args Ignored args.
      */
-    public static void main(String[] args) throws InterruptedException {
+    public static void main(String[] args) {
         TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
 
-        SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
+        SchemaRegistryClient client = new SchemaRegistryClientBuilder()
             .fullyQualifiedNamespace("{schema-registry-endpoint")
             .credential(tokenCredential)
-            .buildAsyncClient();
+            .buildClient();
 
-        CountDownLatch countDownLatch = new CountDownLatch(1);
-        // Register a schema
-        schemaRegistryAsyncClient
-            .getSchema("{schema-id}")
-            .subscribe(schema -> {
-                System.out.println("Successfully retrieved schema.");
-                System.out.printf("Id: %s%nContents: %s%n", schema.getProperties().getId(), schema.getDefinition());
+        // Get a schema using its id. The schema id is generated when it is registered via the client or Azure Portal.
+        SchemaRegistrySchema schema = client.getSchema("{schema-id}");
 
-                countDownLatch.countDown();
-            });
+        System.out.println("Successfully retrieved schema.");
+        System.out.printf("Id: %s%nContents: %s%n", schema.getProperties().getId(), schema.getDefinition());
 
-        // wait for the async task to complete
-        countDownLatch.await();
     }
 }

sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSampleAsync.java

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.data.schemaregistry;
+
+import com.azure.core.credential.TokenCredential;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+import java.util.concurrent.CountDownLatch;
+
+/**
+ * Sample to demonstrate retrieving a schema from Schema Registry using the async client.
+ */
+public class GetSchemaSampleAsync {
+    /**
+     * The main method to run this program.
+     * @param args Ignored args.
+     */
+    public static void main(String[] args) throws InterruptedException {
+        TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
+
+        SchemaRegistryAsyncClient schemaRegistryAsyncClient = new SchemaRegistryClientBuilder()
+            .fullyQualifiedNamespace("{schema-registry-endpoint")
+            .credential(tokenCredential)
+            .buildAsyncClient();
+
+        CountDownLatch countDownLatch = new CountDownLatch(1);
+
+        // Get a schema using its id. The schema id is generated when it is registered via the client or Azure Portal.
+        // `subscribe` is a non-blocking operation. It hooks up the callbacks and then moves onto the next line of code.
+        schemaRegistryAsyncClient
+            .getSchema("{schema-id}")
+            .subscribe(schema -> {
+                System.out.println("Successfully retrieved schema.");
+                System.out.printf("Id: %s%nContents: %s%n", schema.getProperties().getId(), schema.getDefinition());
+
+                countDownLatch.countDown();
+            });
+
+        // wait for the async task to complete
+        countDownLatch.await();
+    }
+}