From 7188fbde09f99024e54d9edf77c900feb7f6cfed Mon Sep 17 00:00:00 2001 From: Connie Yau Date: Tue, 25 Jan 2022 13:27:53 -0800 Subject: [PATCH] Documentation and Sample Fixes for Schema Registry (#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. --- .../README.md | 6 ++- .../apacheavro/ReadmeSamples.java | 4 +- .../azure-data-schemaregistry/README.md | 2 +- .../schemaregistry/SchemaRegistryClient.java | 6 ++- .../SchemaRegistryClientBuilder.java | 2 +- .../src/samples/README.md | 17 ++++--- .../schemaregistry/GetSchemaIdSample.java | 28 +++++------- .../GetSchemaIdSampleAsync.java | 45 +++++++++++++++++++ .../data/schemaregistry/GetSchemaSample.java | 27 +++++------ .../schemaregistry/GetSchemaSampleAsync.java | 43 ++++++++++++++++++ .../schemaregistry/RegisterSchemaSample.java | 23 ++++------ .../RegisterSchemaSampleAsync.java | 45 +++++++++++++++++++ 12 files changed, 188 insertions(+), 60 deletions(-) create mode 100644 sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSampleAsync.java create mode 100644 sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSampleAsync.java create mode 100644 sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSampleAsync.java diff --git a/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/README.md b/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/README.md index 83a2d3797c326..79260030309e6 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/README.md +++ b/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/README.md @@ -52,7 +52,7 @@ with the Azure SDK, please include the `azure-identity` package: com.azure azure-identity - 1.4.1 + 1.4.3 ``` @@ -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(); ``` diff --git a/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/src/samples/java/com/azure/data/schemaregistry/apacheavro/ReadmeSamples.java b/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/src/samples/java/com/azure/data/schemaregistry/apacheavro/ReadmeSamples.java index c35a63c9c805e..72c622618f64f 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry-apacheavro/src/samples/java/com/azure/data/schemaregistry/apacheavro/ReadmeSamples.java +++ b/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 diff --git a/sdk/schemaregistry/azure-data-schemaregistry/README.md b/sdk/schemaregistry/azure-data-schemaregistry/README.md index cd1b65df30e2c..3472b6001b07b 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/README.md +++ b/sdk/schemaregistry/azure-data-schemaregistry/README.md @@ -42,7 +42,7 @@ To use the [DefaultAzureCredential][DefaultAzureCredential] provider shown below com.azure azure-identity - 1.4.1 + 1.4.3 ``` diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java index ea9c5ddaed023..4de85b0c990fa 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java +++ b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java @@ -148,7 +148,8 @@ public Response 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. diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClientBuilder.java b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClientBuilder.java index f557493db8559..7b45111a2151f 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClientBuilder.java +++ b/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(); diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/README.md b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/README.md index f665905d4d6a6..023e90c3f17f9 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/README.md +++ b/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) diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java index 153c135ba66ad..fdf782c6bf914 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java +++ b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSample.java @@ -5,12 +5,13 @@ 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 { @@ -18,25 +19,18 @@ 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()); } } diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSampleAsync.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaIdSampleAsync.java new file mode 100644 index 0000000000000..d116d44e71e59 --- /dev/null +++ b/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(); + } +} diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSample.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSample.java index 03ca58751073a..0f60e3e3ee204 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSample.java +++ b/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(); } } diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSampleAsync.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/GetSchemaSampleAsync.java new file mode 100644 index 0000000000000..e40edf0648a14 --- /dev/null +++ b/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(); + } +} diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSample.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSample.java index 7545e513c289c..586fedd57b281 100644 --- a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSample.java +++ b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSample.java @@ -5,36 +5,31 @@ 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 registering a schema with Schema Registry. + * + * @see RegisterSchemaSampleAsync for the async sample. */ public class RegisterSchemaSample { /** * 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 - .registerSchema("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO) - .subscribe(schemaProperties -> { - System.out.println("Successfully registered a schema with id " + schemaProperties.getId()); - countDownLatch.countDown(); - }); + SchemaProperties schemaProperties = client + .registerSchema("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO); - // wait for the async task to complete - countDownLatch.await(); + System.out.println("Successfully registered a schema with id " + schemaProperties.getId()); } } diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSampleAsync.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSampleAsync.java new file mode 100644 index 0000000000000..7710ee538b55e --- /dev/null +++ b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/RegisterSchemaSampleAsync.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 registering a schema with Schema Registry. + * + * @see RegisterSchemaSample for the sync sample. + */ +public class RegisterSchemaSampleAsync { + /** + * 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); + + // Register a schema + // `subscribe` is a non-blocking operation. It hooks up the callbacks and then moves onto the next line of code. + schemaRegistryAsyncClient + .registerSchema("{group-name}", "{schema-name}", "{schema-string}", SchemaFormat.AVRO) + .subscribe(schemaProperties -> { + System.out.println("Successfully registered a schema with id " + schemaProperties.getId()); + countDownLatch.countDown(); + }); + + // wait for the async task to complete + countDownLatch.await(); + } +}