Skip to content

Commit

Permalink
CodeGen from PR 3538 in test-repo-billy/azure-rest-api-specs
Browse files Browse the repository at this point in the history 
Merge 5e402e6624cbefecb6b32e8a6e44dc0fe0f4654b into 3fa195c1f44ba3a67ffa664584936a781f35d505
  • Loading branch information
SDKAuto committed Dec 10, 2024
1 parent 098ec58 commit d92e610
Show file tree
Hide file tree
Showing 60 changed files with 1,957 additions and 7,446 deletions.
394 changes: 2 additions & 392 deletions sdk/schemaregistry/azure-data-schemaregistry/CHANGELOG.md
View file

Large diffs are not rendered by default.

217 changes: 38 additions & 179 deletions sdk/schemaregistry/azure-data-schemaregistry/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,221 +1,80 @@
# Azure Schema Registry client library for Java
# Azure SchemaRegistry client library for Java

Azure Schema Registry is a schema repository service hosted by Azure Event Hubs, providing schema storage, versioning,
and management. The registry is leveraged by applications to reduce payload size while describing payload structure with
schema identifiers rather than full schemas.
Azure SchemaRegistry client library for Java.

[Source code][source_code] | [Package (Maven)][package_maven] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][sample_readme]
This package contains Microsoft Azure SchemaRegistry client library.

## Getting started

### Prerequisites

- A [Java Development Kit (JDK)][jdk_link], version 8 or later.
- [Azure Subscription][azure_subscription]
- An [Event Hubs schema registry][event_hubs_namespace]
## Documentation

### Include the package
Various documentation is available to help you get started

#### Include the BOM file
- [API reference documentation][docs]
- [Product documentation][product_documentation]

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number.
To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/boms/azure-sdk-bom/README.md).
## Getting started

```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
```
and then include the direct dependency in the dependencies section without the version tag as shown below.
### Prerequisites

```xml
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-data-schemaregistry</artifactId>
</dependency>
</dependencies>
```
- [Java Development Kit (JDK)][jdk] with version 8 or above
- [Azure Subscription][azure_subscription]

#### Include direct dependency
If you want to take dependency on a particular version of the library that is not present in the BOM,
add the direct dependency to your project as follows.
### Adding the package to your product

[//]: # ({x-version-update-start;com.azure:azure-data-schemaregistry;current})
```xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-data-schemaregistry</artifactId>
<version>1.5.0</version>
</dependency>
```
[//]: # ({x-version-update-end})

### Authenticate the client
In order to interact with the Azure Schema Registry service, you'll need to create an instance of the
`SchemaRegistryClient` class through the `SchemaRegistryClientBuilder`. You will need an **endpoint** and an
**API key** to instantiate a client object.

#### Create SchemaRegistryClient with Azure Active Directory Credential

You can authenticate with Azure Active Directory using the [Azure Identity library][azure_identity]. Note that regional endpoints do not support AAD authentication. Create a [custom subdomain][custom_subdomain] for your resource in order to use this type of authentication.

To use the [DefaultAzureCredential][DefaultAzureCredential] provider shown below, or other credential providers provided with the Azure SDK, please include the `azure-identity` package:

[//]: # ({x-version-update-start;com.azure:azure-identity;dependency})
```xml
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.14.2</version>
<artifactId>azure-data-schemaregistry</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
```
[//]: # ({x-version-update-end})

You will also need to [register a new AAD application][register_aad_app] and [grant access][aad_grant_access] to
Schema Registry service.

Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

##### Async client

```java com.azure.data.schemaregistry.schemaregistryasyncclient.construct
DefaultAzureCredential azureCredential = new DefaultAzureCredentialBuilder()
.build();
SchemaRegistryAsyncClient client = new SchemaRegistryClientBuilder()
.fullyQualifiedNamespace("https://<your-schema-registry-endpoint>.servicebus.windows.net")
.credential(azureCredential)
.buildAsyncClient();
```

##### Sync client
### Authentication

```java com.azure.data.schemaregistry.schemaregistryclient.construct
DefaultAzureCredential azureCredential = new DefaultAzureCredentialBuilder()
.build();
SchemaRegistryClient client = new SchemaRegistryClientBuilder()
.fullyQualifiedNamespace("https://<your-schema-registry-endpoint>.servicebus.windows.net")
.credential(azureCredential)
.buildClient();
```
[Azure Identity][azure_identity] package provides the default implementation for authenticating the client.

## Key concepts
### Schemas

A schema has 6 components:
- Group Name: The name of the group of schemas in the Schema Registry instance.
- Schema Name: The name of the schema.
- Schema ID: The ID assigned by the Schema Registry instance for the schema.
- Serialization Type: The format used for serialization of the schema. For example, Avro.
- Schema Content: The string representation of the schema.
- Schema Version: The version assigned to the schema in the Schema Registry instance.

These components play different roles. Some are used as input into the operations and some are outputs. Currently,
[SchemaProperties][schema_properties] only exposes those properties that are potential outputs that are used in
SchemaRegistry operations. Those exposed properties are `Content` and `Id`.

## Examples

* [Register a schema](#register-a-schema)
* [Retrieve a schema's properties](#retrieve-a-schemas-properties)
* [Retrieve a schema](#retrieve-a-schema)

### Register a schema
Register a schema to be stored in the Azure Schema Registry.

```java com.azure.data.schemaregistry.schemaregistryclient.registerschema-avro
String schema = "{\"type\":\"enum\",\"name\":\"TEST\",\"symbols\":[\"UNIT\",\"INTEGRATION\"]}";
SchemaProperties properties = client.registerSchema("{schema-group}", "{schema-name}", schema,
SchemaFormat.AVRO);

System.out.printf("Schema id: %s, schema format: %s%n", properties.getId(), properties.getFormat());
```java com.azure.data.schemaregistry.readme
```

### Retrieve a schema's properties
Retrieve a previously registered schema's properties from the Azure Schema Registry.
### Service API versions

```java com.azure.data.schemaregistry.schemaregistryclient.getschema
SchemaRegistrySchema schema = client.getSchema("{schema-id}");
The client library targets the latest service API version by default.
The service client builder accepts an optional service API version parameter to specify which API version to communicate.

System.out.printf("Schema id: %s, schema format: %s%n", schema.getProperties().getId(),
schema.getProperties().getFormat());
System.out.println("Schema contents: " + schema.getDefinition());
```
#### Select a service API version

### Retrieve a schema
Retrieve a previously registered schema's content and properties from the Azure Schema Registry.

```java com.azure.data.schemaregistry.schemaregistryclient.getschemaproperties
String schemaContent = "{\n"
+ " \"type\" : \"record\", \n"
+ " \"namespace\" : \"SampleSchemaNameSpace\", \n"
+ " \"name\" : \"Person\", \n"
+ " \"fields\" : [\n"
+ " { \n"
+ " \"name\" : \"FirstName\" , \"type\" : \"string\" \n"
+ " }, \n"
+ " { \n"
+ " \"name\" : \"LastName\", \"type\" : \"string\" \n"
+ " }\n"
+ " ]\n"
+ "}";
SchemaProperties properties = client.getSchemaProperties("{schema-group}", "{schema-name}",
schemaContent, SchemaFormat.AVRO);

System.out.println("Schema id: " + properties.getId());
System.out.println("Format: " + properties.getFormat());
System.out.println("Version: " + properties.getVersion());
```
You have the flexibility to explicitly select a supported service API version when initializing a service client via the service client builder.
This ensures that the client can communicate with services using the specified API version.

## Troubleshooting
When selecting an API version, it is important to verify that there are no breaking changes compared to the latest API version.
If there are significant differences, API calls may fail due to incompatibility.

### Enabling Logging
Always ensure that the chosen API version is fully supported and operational for your specific use case and that it aligns with the service's versioning policy.

Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite
their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help
locate the root issue. View the [logging][logging] wiki for guidance about enabling logging.
## Troubleshooting

## Next steps
More samples can be found [here][samples].

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-java/blob/main/CONTRIBUTING.md).

This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments.
1. Fork it
1. Create your feature branch (`git checkout -b my-new-feature`)
1. Commit your changes (`git commit -am 'Add some feature'`)
1. Push to the branch (`git push origin my-new-feature`)
1. Create new Pull Request

<!-- LINKS -->
[package_maven]: https://central.sonatype.com/artifact/com.azure/azure-data-schemaregistry
[sample_readme]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples
[samples]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry
[source_code]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/src
[samples_code]: src/samples/
[product_documentation]: https://azure.microsoft.com/services/
[docs]: https://azure.github.io/azure-sdk-for-java/
[jdk]: https://learn.microsoft.com/azure/developer/java/fundamentals/
[azure_subscription]: https://azure.microsoft.com/free/
[api_reference_doc]: https://azure.github.io/azure-sdk-for-java/
[azure_cli]: https://docs.microsoft.com/cli/azure
[azure_portal]: https://portal.azure.com
[azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/identity/azure-identity
[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity/README.md#defaultazurecredential
[event_hubs_namespace]: https://learn.microsoft.com/azure/event-hubs/create-schema-registry
[jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
[product_documentation]: https://aka.ms/schemaregistry
[custom_subdomain]: https://docs.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain
[register_aad_app]: https://docs.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal
[aad_grant_access]: https://docs.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal
[schema_properties]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/models/SchemaProperties.java
[logging]: https://github.com/Azure/azure-sdk-for-java/wiki/Logging-in-Azure-SDK
[cla]: https://cla.microsoft.com
[coc]: https://opensource.microsoft.com/codeofconduct/
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
[coc_contact]: mailto:[email protected]
[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fschemaregistry%2Fazure-data-schemaregistry%2FREADME.png)
7 changes: 1 addition & 6 deletions sdk/schemaregistry/azure-data-schemaregistry/assets.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1 @@
{
"AssetsRepo": "Azure/azure-sdk-assets",
"AssetsRepoPrefixPath": "java",
"TagPrefix": "java/schemaregistry/azure-data-schemaregistry",
"Tag": "java/schemaregistry/azure-data-schemaregistry_1eb85e2a8b"
}
{"AssetsRepo":"Azure/azure-sdk-assets","AssetsRepoPrefixPath":"java","TagPrefix":"java/schemaregistry/azure-data-schemaregistry","Tag":""}
6 changes: 0 additions & 6 deletions sdk/schemaregistry/azure-data-schemaregistry/checkstyle-suppressions.xml
View file

This file was deleted.

65 changes: 25 additions & 40 deletions sdk/schemaregistry/azure-data-schemaregistry/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
<!--
~ Copyright (c) Microsoft Corporation. All rights reserved.
~ Licensed under the MIT License.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
~ Copyright (c) Microsoft Corporation. All rights reserved.
~ Licensed under the MIT License.
~ Code generated by Microsoft (R) TypeSpec Code Generator.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>com.azure</groupId>
<artifactId>azure-client-sdk-parent</artifactId>
Expand All @@ -16,42 +14,37 @@

<groupId>com.azure</groupId>
<artifactId>azure-data-schemaregistry</artifactId>
<version>1.0.0-beta.1</version> <!-- {x-version-update;com.azure:azure-data-schemaregistry;current} -->
<packaging>jar</packaging>
<version>1.6.0-beta.1</version> <!-- {x-version-update;com.azure:azure-data-schemaregistry;current} -->

<name>Microsoft Azure client library for Schema Registry</name>
<description>This package contains the Microsoft Azure Schema Registry client library</description>
<name>Microsoft Azure SDK for SchemaRegistry</name>
<description>This package contains Microsoft Azure SchemaRegistry client library.</description>
<url>https://github.com/Azure/azure-sdk-for-java</url>

<distributionManagement>
<site>
<id>azure-java-build-docs</id>
<url>${site.url}/site/${project.artifactId}</url>
</site>
</distributionManagement>
<licenses>
<license>
<name>The MIT License (MIT)</name>
<url>http://opensource.org/licenses/MIT</url>
<distribution>repo</distribution>
</license>
</licenses>

<scm>
<url>scm:git:https://github.com/Azure/azure-sdk-for-java</url>
<url>https://github.com/Azure/azure-sdk-for-java</url>
<connection>scm:git:[email protected]:Azure/azure-sdk-for-java.git</connection>
<developerConnection>scm:git:[email protected]:Azure/azure-sdk-for-java.git</developerConnection>
<tag>HEAD</tag>
</scm>

<developers>
<developer>
<id>microsoft</id>
<name>Microsoft</name>
</developer>
</developers>
<properties>
<!-- Configures the Java 9+ run to perform the required module exports, opens, and reads that are necessary for testing but shouldn't be part of the module-info. -->
<javaModulesSurefireArgLine>
--add-opens com.azure.core/com.azure.core.implementation.util=ALL-UNNAMED
--add-opens com.azure.data.schemaregistry/com.azure.data.schemaregistry=ALL-UNNAMED

--add-exports com.azure.core/com.azure.core.implementation.util=ALL-UNNAMED
--add-exports com.azure.data.schemaregistry/com.azure.data.schemaregistry.implementation.models=ALL-UNNAMED
</javaModulesSurefireArgLine>
<checkstyle.excludes>**/implementation/**/*.java</checkstyle.excludes>

<checkstyle.suppressionsLocation>checkstyle-suppressions.xml</checkstyle.suppressionsLocation>
<spotbugs.skip>false</spotbugs.skip>
<spotbugs.excludeFilterFile>spotbugs-exclude.xml</spotbugs.excludeFilterFile>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<spotless.skip>false</spotless.skip>
</properties>

<dependencies>
<dependency>
<groupId>com.azure</groupId>
Expand All @@ -63,14 +56,6 @@
<artifactId>azure-core-http-netty</artifactId>
<version>1.15.7</version> <!-- {x-version-update;com.azure:azure-core-http-netty;dependency} -->
</dependency>

<!-- Test dependencies -->
<dependency>
<groupId>org.apache.avro</groupId>
<artifactId>avro</artifactId>
<version>1.11.4</version> <!-- {x-version-update;org.apache.avro:avro;external_dependency} -->
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-core-test</artifactId>
Expand Down
2 changes: 0 additions & 2 deletions ...aregistry/azure-data-schemaregistry/resources/azure-data-schemaregistry-client.properties
View file

This file was deleted.

22 changes: 0 additions & 22 deletions sdk/schemaregistry/azure-data-schemaregistry/spotbugs-exclude.xml
View file

This file was deleted.

Loading

0 comments on commit d92e610

Please sign in to comment.