search

Azure / azure-sdk-for-java

This repository is for active development of the Azure SDK for Java. For consumers of the SDK we recommend visiting our public developer docs at https://docs.microsoft.com/java/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-java.
MIT License
2.35k stars 1.99k forks source link

[FEATURE REQ] Make each Azure Spring Identifier only used in one place. #26197

Closed chenrujun closed 2 years ago

chenrujun commented 2 years ago

Current problem

Now some Azure Spring Identifier be used in more than one place.

  1. az-sp-kv-ct be used in AzureKeyVaultCertificateAutoConfiguration and azure-security-keyvault-jca-user-agent-value-prefix.txt.
  2. az-sp-eh be used in AzureBlobCheckpointStoreConfiguration, AzureEventHubsClientBuilderConfiguration, DedicatedConsumerConnectionConfiguration, AzureEventHubsProcessorClientConfiguration, AzureEventHubsClientBuilderConfiguration
  3. az-sp-bus be used in PremiumServiceBusJmsAutoConfiguration, AzureServiceBusClientBuilderConfiguration, NoneSessionConsumerClientConfiguration, SessionConsumerClientConfiguration, NoneSessionProcessorClientConfiguration, SessionProcessorClientConfiguration, AzureServiceBusProducerClientConfiguration
  4. az-si-sb be used in DefaultServiceBusNamespaceProcessorFactory(2 places), DefaultServiceBusNamespaceProducerFactory.
  5. az-si-eh be used in DefaultEventHubsNamespaceProcessorFactory, DefaultEventHubsNamespaceProducerFactory.

Solution

Design new identifier for every usage scenario.

Identifier max length

Because ClientOptions#MAX_APPLICATION_ID_LENGTH=24, and we may have version like 4.0.0.beta-1 which length is 12. The remaining length is 24 - 12 = 12.

Identifier format.

Identifier prefix.

About identifier prefix, 2 options come into mind:

Option 1: Keep same with version 3.x. Use az-sp- as prefix.

Here is the identifiers used in version 3.x:

ApplicationId Description
az-se-kv-jca Azure Security KeyVault JCA
az-sp-kv-ct Azure Spring KeyVault Certificates
az-sp-kv Azure Spring KeyVault Secrets
az-sp-bus Azure Spring Service Bus
az-sp-sb Azure Spring Storage Blob
az-sp-sf Azure Spring Storage Files
az-sp-aad Azure Spring Active Directory
az-sp-b2c Azure Spring Active Directory B2C

Pros:

  1. Keep same with previous version.
  2. az-sp- is not easy to have conflict with other User-Agent.

Cons:

  1. The length of az-sp- is 6, there will be only 12-6=6 left. It may not enough to encode all identifiers.
Option 2: Use as- as prefix.

Pros:

  1. There will be 12-3=9 left.

Cons:

  1. The possibility of conflicting with other User-Agent is much higher.
  2. Not same with previous version. Which means we need more efforts to maintain the logic of BI.

I decide to choose option 1: Use az-sp- as prefix.

Identifier suffix

In version 3.x, we already have identifier like az-sp-kv-ct, which means Azure Spring KeyVault Certificate. We can continue this style: Use abbreviation as suffix.

But Some services have many scenarios, for example, Now there are 10 identifiers about ServiceBus.

Usage
AzureServiceBusClientBuilderConfiguration#serviceBusClientBuilderFactory
DefaultServiceBusNamespaceProcessorFactory#doCreateProcessor#sessionEnabled=false
DefaultServiceBusNamespaceProducerFactory#doCreateProducer
DefaultServiceBusNamespaceProcessorFactory#doCreateProcessor#sessionEnabled=true
AzureServiceBusProcessorClientConfiguration#NoneSessionProcessorClientConfiguration#serviceBusProcessorClientBuilderFactory
AzureServiceBusConsumerClientConfiguration#NoneSessionConsumerClientConfiguration#serviceBusReceiverClientBuilderFactory
PremiumServiceBusJmsAutoConfiguration#jmsConnectionFactory
AzureServiceBusProducerClientConfiguration#serviceBusSenderClientBuilderFactory
AzureServiceBusProcessorClientConfiguration#SessionProcessorClientConfiguration#serviceBusSessionProcessorClientBuilderFactory
AzureServiceBusConsumerClientConfiguration#SessionConsumerClientConfiguration#serviceBusSessionReceiverClientBuilderFactory

We can use az-sp-sb-nc for Azure Spring ServiceBus Namespace No Sessioon Processor Client. and az-sp-sb-sc for Azure Spring ServiceBus Namespace Sender Client Builder Factory. But after we use abbreviations like this, it's hard to know what does az-sp-sb-nc mean.

And after the project continue developing, there maybe more identifiers come up. It's hard to manage these abbreviations.

Here is one solution: Use number instead of abbreviations. For example: az-sp-sb-01 means Azure Spring ServiceBus Client Builder Factory, and az-sp-sb-02 means Azure Spring ServiceBus Namespace No Session Processor Client.

If we add new identifiers for ServiceBus in the future, we just need to increase number: 01 -> 02 -> 03 -> ... -> 99 -> 00 (10 10 = 100 in total). If we still have more identifiers, we can use aa -> ab -> ac -> zz (26 26 in total), I think that's enough.

Identifier table.

Identifier value and description

NO Identifer value Description
1 az-se-kv-jc Azure Seciruty KeyVault Jca
2 az-sp-ac-01 Azure Spring App Configuration Client Builder Factory
3 az-sp-ad-01 Azure Spring Azure Active Directory Authorization Code Grant Request
4 az-sp-bc-01 Azure Spring Azure Active Directory B2C Authorization Code Grant Request
5 az-sp-bs-01 Azure Spring BlobService Client Builder Factory
6 az-sp-bs-02 Azure Spring Blog Service Eveht Hub Processor Blob Service Client Builder Factory
7 az-sp-cs-01 Azure Spring Cosmos Client Builder Factory
8 az-sp-eh-01 Azure Spring EventHubs Client Builder Factory
9 az-sp-eh-02 Azure Spring EventHubs Client Builder Factory for Consumer
10 az-sp-eh-03 Azure Spring EventHubs Client Builder Factory for Processor
11 az-sp-eh-04 Azure Spring EventHubs Client Builder Factory for Produder
12 az-sp-eh-05 Azure Spring EventHubs Namespace Processor Client Builder Factory
13 az-sp-eh-06 Azure Spring EventHubs Namespace Producer Client Builder Factory
14 az-sp-kv-01 Azure Spring KeyVault Certificate Client Builder Factory
15 az-sp-kv-02 Azure Spring KeyVault Certificate JCA
16 az-sp-kv-03 Azure Spring KeyVault Secret Client Fuilder Factory
17 az-sp-qs-01 Azure Spring QueueService Client Builder Factory
18 az-sp-sb-01 Azure Spring ServiceBus Client Builder Factory
19 az-sp-sb-02 Azure Spring ServiceBus Namespace No Session Processor Client
20 az-sp-sb-03 Azure Spring ServiceBus Namespace Sender Client Builder Factory
21 az-sp-sb-04 Azure Spring ServiceBus Namespace Session Processor Client
22 az-sp-sb-05 Azure Spring ServiceBus No Session Processor Client Builder Factory
23 az-sp-sb-06 Azure Spring ServiceBus No Session Receiver Client Builder Factory
24 az-sp-sb-07 Azure Spring ServiceBus Premium Connection Factory
25 az-sp-sb-08 Azure Spring ServiceBus Sender Client Builder Factory
26 az-sp-sb-09 Azure Spring ServiceBus Session Processor Client Builder Factory
27 az-sp-sb-10 Azure Spring ServiceBus Session Receiver Client Builder Factory
28 az-sp-ss-01 Azure Spring ShareService Client Builder Factory

Identifier value and usage

NO Identifer value Where to use
1 az-se-kv-jc HttpUtil.DEFAULT_USER_AGENT_VALUE_PREFIX
2 az-sp-ac-01 AzureAppConfigurationAutoConfiguration#configurationClientBuilderFactory
3 az-sp-ad-01 AADOAuth2AuthorizationCodeGrantRequestEntityConverter
4 az-sp-bc-01 AADB2COAuth2AuthorizationCodeGrantRequestEntityConverter
5 az-sp-bs-01 AzureStorageBlobAutoConfiguration#blobServiceClientBuilderFactory
6 az-sp-bs-02 AzureBlobCheckpointStoreConfiguration#eventHubProcessorBlobServiceClientBuilderFactory
7 az-sp-cs-01 AzureCosmosAutoConfiguration#cosmosClientBuilderFactory
8 az-sp-eh-01 AzureEventHubsClientBuilderConfiguration#eventHubClientBuilderFactory
9 az-sp-eh-02 AzureEventHubsConsumerClientConfiguration#DedicatedConsumerConnectionConfiguration#eventHubClientBuilderFactoryForConsumer
10 az-sp-eh-03 AzureEventHubsProcessorClientConfiguration#eventProcessorClientBuilderFactory
11 az-sp-eh-04 AzureEventHubsProducerClientConfiguration#DedicatedProducerConnectionConfiguration#eventHubClientBuilderFactoryForProducer
12 az-sp-eh-05 DefaultEventHubsNamespaceProcessorFactory#doCreateProcessor
13 az-sp-eh-06 DefaultEventHubsNamespaceProducerFactory#doCreateProducer
14 az-sp-kv-01 AzureKeyVaultCertificateAutoConfiguration#certificateClientBuilderFactory
15 az-sp-kv-02 azure-security-keyvault-jca-user-agent-value-prefix.txt
16 az-sp-kv-03 AzureKeyVaultSecretAutoConfiguration#secretClientBuilderFactory
17 az-sp-qs-01 AzureStorageQueueAutoConfiguration#queueServiceClientBuilderFactory
18 az-sp-sb-01 AzureServiceBusClientBuilderConfiguration#serviceBusClientBuilderFactory
19 az-sp-sb-02 DefaultServiceBusNamespaceProcessorFactory#doCreateProcessor#sessionEnabled=false
20 az-sp-sb-03 DefaultServiceBusNamespaceProducerFactory#doCreateProducer
21 az-sp-sb-04 DefaultServiceBusNamespaceProcessorFactory#doCreateProcessor#sessionEnabled=true
22 az-sp-sb-05 AzureServiceBusProcessorClientConfiguration#NoneSessionProcessorClientConfiguration#serviceBusProcessorClientBuilderFactory
23 az-sp-sb-06 AzureServiceBusConsumerClientConfiguration#NoneSessionConsumerClientConfiguration#serviceBusReceiverClientBuilderFactory
24 az-sp-sb-07 PremiumServiceBusJmsAutoConfiguration#jmsConnectionFactory
25 az-sp-sb-08 AzureServiceBusProducerClientConfiguration#serviceBusSenderClientBuilderFactory
26 az-sp-sb-09 AzureServiceBusProcessorClientConfiguration#SessionProcessorClientConfiguration#serviceBusSessionProcessorClientBuilderFactory
27 az-sp-sb-10 AzureServiceBusConsumerClientConfiguration#SessionConsumerClientConfiguration#serviceBusSessionReceiverClientBuilderFactory
28 az-sp-ss-01 AzureStorageFileShareAutoConfiguration#shareServiceClientBuilderFactory

Tasks

chenrujun commented 2 years ago

Closing this issue. Use this issue to track new identifier design: Redesign: #26203