Skip to content

Commit

Permalink
Revamp KV Javadocs (#34545)
Browse files Browse the repository at this point in the history
  • Loading branch information
@g2vinay
g2vinay authored Sep 14, 2023
1 parent c2e318b commit 3f261df
Show file tree
Hide file tree
Showing 17 changed files with 1,351 additions and 51 deletions.
108 changes: 100 additions & 8 deletions ...icates/src/main/java/com/azure/security/keyvault/certificates/CertificateAsyncClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,34 @@
import static com.azure.core.util.FluxUtil.withContext;

/**
* The CertificateAsyncClient provides asynchronous methods to manage {@link KeyVaultCertificate certifcates} in the Azure Key Vault. The client
* supports creating, retrieving, updating, merging, deleting, purging, backing up, restoring and listing the
* {@link KeyVaultCertificate certificates}. The client also supports listing {@link DeletedCertificate deleted certificates} for
* a soft-delete enabled Azure Key Vault.
* The CertificateAsyncClient provides asynchronous methods to manage {@link KeyVaultCertificate certifcates} in
* a key vault. The client supports creating, retrieving, updating, merging, deleting, purging, backing up,
* restoring and listing the {@link KeyVaultCertificate certificates}. The client also supports listing
* {@link DeletedCertificate deleted certificates} for a soft-delete enabled key vault.
*
* <p>The client further allows creating, retrieving, updating, deleting and listing the {@link CertificateIssuer certificate issuers}. The client also supports
* creating, listing and deleting {@link CertificateContact certificate contacts}</p>
* <p>The client further allows creating, retrieving, updating, deleting and listing the
* {@link CertificateIssuer certificate issuers}. The client also supports creating, listing and deleting
* {@link CertificateContact certificate contacts}.</p>
*
* <p><strong>Samples to construct the async client</strong></p>
* <h2>Getting Started</h2>
*
* <p>In order to interact with the Azure Key Vault service, you will need to create an instance of the
* {@link CertificateAsyncClient} class, a vault url and a credential object.</p>
*
* <p>The examples shown in this document use a credential object named DefaultAzureCredential for authentication,
* which is appropriate for most scenarios, including local development and production environments. Additionally,
* we recommend using a
* <a href="https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/">
* managed identity</a> for authentication in production environments.
* You can find more information on different ways of authenticating and their corresponding credential types in the
* <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable">
* Azure Identity documentation"</a>.</p>
*
* <p><strong>Sample: Construct Asynchronous Certificate Client</strong></p>
*
* <p>The following code sample demonstrates the creation of a
* {@link com.azure.security.keyvault.certificates.CertificateAsyncClient}, using the
* {@link com.azure.security.keyvault.certificates.CertificateClientBuilder} to configure it.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateAsyncClient.instantiation -->
* <pre>
Expand All @@ -61,8 +80,81 @@
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateAsyncClient.instantiation -->
*
* <br/>
*
* <hr/>
*
* <h2>Create a Certificate</h2>
* The {@link CertificateAsyncClient} can be used to create a certificate in the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to asynchronously create a certificate in the key vault,
* using the {@link CertificateAsyncClient#beginCreateCertificate(String, CertificatePolicy)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateAsyncClient.beginCreateCertificate#String-CertificatePolicy -->
* <pre>
* CertificatePolicy certPolicy = new CertificatePolicy&#40;&quot;Self&quot;, &quot;CN=SelfSignedJavaPkcs12&quot;&#41;;
* certificateAsyncClient.beginCreateCertificate&#40;&quot;certificateName&quot;, certPolicy&#41;
* .subscribe&#40;pollResponse -&gt; &#123;
* System.out.println&#40;&quot;---------------------------------------------------------------------------------&quot;&#41;;
* System.out.println&#40;pollResponse.getStatus&#40;&#41;&#41;;
* System.out.println&#40;pollResponse.getValue&#40;&#41;.getStatus&#40;&#41;&#41;;
* System.out.println&#40;pollResponse.getValue&#40;&#41;.getStatusDetails&#40;&#41;&#41;;
* &#125;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateAsyncClient.beginCreateCertificate#String-CertificatePolicy -->
*
* <p><strong>Note:</strong> For the synchronous sample, refer to {@link CertificateClient}.</p>
*
* <br/>
*
* <hr/>
*
* <h2>Get a Certificate</h2>
* The {@link CertificateAsyncClient} can be used to retrieve a certificate from the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to asynchronously retrieve a certificate from the key vault, using
* the {@link CertificateAsyncClient#getCertificate(String)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateAsyncClient.getCertificate#String -->
* <pre>
* certificateAsyncClient.getCertificate&#40;&quot;certificateName&quot;&#41;
* .contextWrite&#40;Context.of&#40;key1, value1, key2, value2&#41;&#41;
* .subscribe&#40;certificateResponse -&gt;
* System.out.printf&#40;&quot;Certificate is returned with name %s and secretId %s %n&quot;,
* certificateResponse.getProperties&#40;&#41;.getName&#40;&#41;, certificateResponse.getSecretId&#40;&#41;&#41;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateAsyncClient.getCertificate#String -->
*
* <p><strong>Note:</strong> For the synchronous sample, refer to {@link CertificateClient}.</p>
*
* <br/>
*
* <hr/>
*
* <h2>Delete a Certificate</h2>
* The {@link CertificateAsyncClient} can be used to delete a certificate from the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to asynchronously delete a certificate from the Azure
* KeyVault, using the {@link CertificateAsyncClient#beginDeleteCertificate(String)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateAsyncClient.beginDeleteCertificate#String -->
* <pre>
* certificateAsyncClient.beginDeleteCertificate&#40;&quot;certificateName&quot;&#41;
* .subscribe&#40;pollResponse -&gt; &#123;
* System.out.println&#40;&quot;Delete Status: &quot; + pollResponse.getStatus&#40;&#41;.toString&#40;&#41;&#41;;
* System.out.println&#40;&quot;Delete Certificate Name: &quot; + pollResponse.getValue&#40;&#41;.getName&#40;&#41;&#41;;
* System.out.println&#40;&quot;Certificate Delete Date: &quot; + pollResponse.getValue&#40;&#41;.getDeletedOn&#40;&#41;.toString&#40;&#41;&#41;;
* &#125;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateAsyncClient.beginDeleteCertificate#String -->
*
* <p><strong>Note:</strong> For the synchronous sample, refer to {@link CertificateClient}.</p>
*
* @see com.azure.security.keyvault.certificates
* @see CertificateClientBuilder
* @see PagedFlux
*/
@ServiceClient(builder = CertificateClientBuilder.class, isAsync = true, serviceInterfaces = CertificateClientImpl.CertificateService.class)
public final class CertificateAsyncClient {
Expand Down
106 changes: 97 additions & 9 deletions ...ertificates/src/main/java/com/azure/security/keyvault/certificates/CertificateClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,33 @@


/**
* The CertificateClient provides synchronous methods to manage {@link KeyVaultCertificate certifcates} in the Azure Key Vault. The client
* supports creating, retrieving, updating, merging, deleting, purging, backing up, restoring and listing the
* {@link KeyVaultCertificate certificates}. The client also supports listing {@link DeletedCertificate deleted certificates} for
* a soft-delete enabled Azure Key Vault.
* The {@link CertificateClient} provides synchronous methods to manage {@link KeyVaultCertificate certifcates} in
* the key vault. The client supports creating, retrieving, updating, merging, deleting, purging, backing up,
* restoring and listing the {@link KeyVaultCertificate certificates}. The client also supports listing
* {@link DeletedCertificate deleted certificates} for a soft-delete enabled key vault.
*
* <p>The client further allows creating, retrieving, updating, deleting and listing the {@link CertificateIssuer certificate issuers}. The client also supports
* creating, listing and deleting {@link CertificateContact certificate contacts}</p>
* <p>The client further allows creating, retrieving, updating, deleting and listing the
* {@link CertificateIssuer certificate issuers}. The client also supports creating, listing and
* deleting {@link CertificateContact certificate contacts}.</p>
*
* <p><strong>Samples to construct the sync client</strong></p>
* <h2>Getting Started</h2>
*
* <p>In order to interact with the Azure Key Vault service, you will need to create an instance of the
* {@link CertificateClient} class, a vault url and a credential object.</p>
*
* <p>The examples shown in this document use a credential object named DefaultAzureCredential for authentication,
* which is appropriate for most scenarios, including local development and production environments. Additionally,
* we recommend using a
* <a href="https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/">
* managed identity</a> for authentication in production environments.
* You can find more information on different ways of authenticating and their corresponding credential types in the
* <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable">
* Azure Identity documentation"</a>.</p>
*
* <p><strong>Sample: Construct Synchronous Certificate Client</strong></p>
*
* <p>The following code sample demonstrates the creation of a {@link CertificateClient},
* using the {@link CertificateClientBuilder} to configure it.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateClient.instantiation -->
* <pre>
Expand All @@ -52,10 +70,80 @@
* .httpLogOptions&#40;new HttpLogOptions&#40;&#41;.setLogLevel&#40;HttpLogDetailLevel.BODY_AND_HEADERS&#41;&#41;
* .buildClient&#40;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateClient.instantiation -->
* <!-- end com.azure.security.keyvault.certificates.CertificateClient.instantiation -->
*
* <br/>
*
* <hr/>
*
* <h2>Create a Certificate</h2>
* The {@link CertificateClient} can be used to create a certificate in the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to synchronously create a certificate in the key vault,
* using the {@link CertificateClient#beginCreateCertificate(String, CertificatePolicy)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateClient.beginCreateCertificate#String-CertificatePolicy -->
* <pre>
* CertificatePolicy certPolicy = new CertificatePolicy&#40;&quot;Self&quot;,
* &quot;CN=SelfSignedJavaPkcs12&quot;&#41;;
* SyncPoller&lt;CertificateOperation, KeyVaultCertificateWithPolicy&gt; certPoller = certificateClient
* .beginCreateCertificate&#40;&quot;certificateName&quot;, certPolicy&#41;;
* certPoller.waitUntil&#40;LongRunningOperationStatus.SUCCESSFULLY_COMPLETED&#41;;
* KeyVaultCertificate cert = certPoller.getFinalResult&#40;&#41;;
* System.out.printf&#40;&quot;Certificate created with name %s%n&quot;, cert.getName&#40;&#41;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateClient.beginCreateCertificate#String-CertificatePolicy -->
*
* <p><strong>Note:</strong> For the asynchronous sample, refer to {@link CertificateAsyncClient}.</p>
*
* <br/>
*
* <hr/>
*
* <h2>Get a Certificate</h2>
* The {@link CertificateClient} can be used to retrieve a certificate from the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to synchronously retrieve a certificate from the key vault, using
* the {@link CertificateClient#getCertificate(String)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateClient.getCertificatePolicy#string -->
* <pre>
* CertificatePolicy policy = certificateClient.getCertificatePolicy&#40;&quot;certificateName&quot;&#41;;
* System.out.printf&#40;&quot;Received policy with subject name %s%n&quot;, policy.getSubject&#40;&#41;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateClient.getCertificatePolicy#string -->
*
* <p><strong>Note:</strong> For the asynchronous sample, refer to {@link CertificateAsyncClient}.</p>
*
* <br/>
*
* <hr/>
*
* <h2>Delete a Certificate</h2>
* The {@link CertificateClient} can be used to delete a certificate from the key vault.
*
* <p><strong>Code Sample:</strong></p>
* <p>The following code sample demonstrates how to synchronously delete a certificate from the
* key vault, using the {@link CertificateClient#beginDeleteCertificate(String)} API.</p>
*
* <!-- src_embed com.azure.security.keyvault.certificates.CertificateClient.beginDeleteCertificate#String -->
* <pre>
* SyncPoller&lt;DeletedCertificate, Void&gt; deleteCertPoller =
* certificateClient.beginDeleteCertificate&#40;&quot;certificateName&quot;&#41;;
* &#47;&#47; Deleted Certificate is accessible as soon as polling beings.
* PollResponse&lt;DeletedCertificate&gt; deleteCertPollResponse = deleteCertPoller.poll&#40;&#41;;
* System.out.printf&#40;&quot;Deleted certificate with name %s and recovery id %s%n&quot;,
* deleteCertPollResponse.getValue&#40;&#41;.getName&#40;&#41;, deleteCertPollResponse.getValue&#40;&#41;.getRecoveryId&#40;&#41;&#41;;
* deleteCertPoller.waitForCompletion&#40;&#41;;
* </pre>
* <!-- end com.azure.security.keyvault.certificates.CertificateClient.beginDeleteCertificate#String -->
*
* <p><strong>Note:</strong> For the asynchronous sample, refer to {@link CertificateAsyncClient}.</p>
*
* @see com.azure.security.keyvault.certificates
* @see CertificateClientBuilder
* @see PagedIterable
*/
@ServiceClient(builder = CertificateClientBuilder.class, serviceInterfaces = CertificateClientImpl.CertificateService.class)
public final class CertificateClient {
Expand Down
Loading

0 comments on commit 3f261df

Please sign in to comment.