diff --git a/sdk/tables/azure-data-tables/README.md b/sdk/tables/azure-data-tables/README.md index 1f0ecaa7a0dcb..1e5415848b442 100644 --- a/sdk/tables/azure-data-tables/README.md +++ b/sdk/tables/azure-data-tables/README.md @@ -149,6 +149,7 @@ Common uses of the Table service include: #### Authenticate with a connection string To use a connection string to authorize your client, call the builder's `connectionString` method with your connection string. + ```java TableServiceClient tableServiceClient = new TableServiceClientBuilder() .connectionString("") @@ -158,6 +159,7 @@ TableServiceClient tableServiceClient = new TableServiceClientBuilder() #### Authenticate with a Shared Key To use a Shared Key to authorize your client, create an instance of `TablesSharedKeyCredential` with your account name and access key. Call the builder's `endpoint` method with your account URL and the `credential` method with the `TablesSharedKeyCredential` object you created. + ```java TablesSharedKeyCredential credential = new TablesSharedKeyCredential("", ""); TableServiceClient tableServiceClient = new TableServiceClientBuilder() @@ -169,6 +171,7 @@ TableServiceClient tableServiceClient = new TableServiceClientBuilder() #### Authenticate with a Shared Access Signature (SAS) To use a SAS to authorize your client, call the builder's `endpoint` method with your account URL and the `sasToken` method with your SAS. + ```java TableServiceClient tableServiceClient = new TableServiceClientBuilder() .endpoint("") @@ -181,21 +184,24 @@ TableServiceClient tableServiceClient = new TableServiceClientBuilder() #### Construct a `TableServiceClient` Construct a `TableServiceClient` by creating an instance of `TableServiceClientBuilder` and then calling the builder's `buildClient` or `buildAsyncClient` methods. + ```java TableServiceClient tableServiceClient = new TableServiceClientBuilder() .connectionString("") // or use any of the other authentication methods .buildClient(); -```a +``` #### Create a table Create a table by calling the `TableServiceClient`'s `createTable` method. An exception will be thrown if a table with the provided name exists. + ```java tableServiceClient.createTable(tableName); ``` Alternatively, you can call the `createTableIfNotExists` method which will create the table only if no such table exists, and does not throw an exception. + ```java tableServiceClient.createTableIfNotExists(tableName); ``` @@ -203,6 +209,7 @@ tableServiceClient.createTableIfNotExists(tableName); #### List tables List or query the set of existing tables by calling the `TableServiceClient`'s `listTables` method, optionally passing in a `ListTablesOptions` instance to filter or limit the query results. See [Supported Query Options][query_options] for details about supported query options. + ```java ListTablesOptions options = new ListTablesOptions() .setFilter(String.format("TableName eq '%s'", tableName)); @@ -215,6 +222,7 @@ for (TableItem tableItem : tableServiceClient.listTables(options)) { #### Delete a table Delete a table by calling the `TableServiceClient`'s `deleteTable` method. An exception will be thrown if no table with the provided name exists. + ```java tableServiceClient.deleteTable(tableName); ``` @@ -224,6 +232,7 @@ tableServiceClient.deleteTable(tableName); #### Construct a `TableClient` Construct a `TableClient` by creating an instance of `TableClientBuilder`, calling the builder's `tableName` method with the name of the table, and then calling its `buildClient` or `buildAsyncClient` methods. + ```java TableClient tableClient = new TableClientBuilder() .connectionString("") // or use any of the other authentication methods @@ -233,6 +242,7 @@ TableClient tableClient = new TableClientBuilder() Alternatively, a `TableClient` can be retrieved from an existing `TableServiceClient` by calling its `getTableClient` method. + ```java TableClient tableClient = tableServiceClient.getTableClient(tableName); ``` @@ -240,6 +250,7 @@ TableClient tableClient = tableServiceClient.getTableClient(tableName); #### Create an entity Create a new `TableEntity` instance, providing the partition key and row key of the entity to create, optionally adding properties to the created object. Then pass the object to the `TableClient`'s `createEntity` method. An exception will be thrown if an entity with the provided partition key and row key exists within the table. + ```java TableEntity entity = new TableEntity(partitionKey, rowKey) .addProperty("Product", "Marker Set") @@ -249,28 +260,25 @@ TableEntity entity = new TableEntity(partitionKey, rowKey) tableClient.createEntity(entity); ``` -Alternatively, you can call the `createEntityIfNotExists` method which will create the entity only if no entity with the provided partition key and row key exists within the table, and does not throw an exception. - -```java -tableClient.createEntityIfNotExists(entity); -``` - #### List entities List or query the set of entities within the table by calling the `TableClient`'s `listEntities` method, optionally passing in a `ListEntitiesOptions` instance to filter, select, or limit the query results. See [Supported Query Options][query_options] for details about supported query options. + ```java ListEntitiesOptions options = new ListEntitiesOptions() .setFilter(String.format("PartitionKey eq '%s'", partitionKey)) .setSelect("Product, Price"); for (TableEntity entity : tableClient.listEntities(options)) { - System.out.println(String.format("%s: %.2f", entity.getProperty("Product"), entity.getProperty("Price"))); + Map properties = entity.getProperties(); + System.out.println(String.format("%s: %.2f", properties.get("Product"), properties.get("Price"))); } ``` #### Delete an entity Delete an entity by calling the `TableClient`'s `deleteEntity` method. An exception will be thrown if no entity with the provided partition key and row key exists. + ```java tableClient.deleteEntity(partitionKey, rowKey); ``` @@ -282,6 +290,7 @@ When you interact with Tables service using the Azure Tables library for Java, e For example, if you try to create a table that already exists, a `409` error is returned, indicating "Conflict". + ```java // Create the table if it doesn't already exist. tableServiceClient.createTableIfNotExists(tableName); @@ -289,8 +298,8 @@ tableServiceClient.createTableIfNotExists(tableName); // Now attempt to create the same table unconditionally. try { tableServiceClient.createTable(tableName); -} catch (TableServiceErrorException e) { - System.out.println(e.getResponse().getStatusCode()); // 409 +} catch (TableStorageException e) { + System.out.println(e.getStatusCode()); // 409 } ``` diff --git a/sdk/tables/azure-data-tables/src/samples/java/ReadmeSamples.java b/sdk/tables/azure-data-tables/src/samples/java/ReadmeSamples.java new file mode 100644 index 0000000000000..a2128783dcb1e --- /dev/null +++ b/sdk/tables/azure-data-tables/src/samples/java/ReadmeSamples.java @@ -0,0 +1,167 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +package com.azure.data.tables; + +import com.azure.data.tables.models.ListEntitiesOptions; +import com.azure.data.tables.models.ListTablesOptions; +import com.azure.data.tables.models.TableEntity; +import com.azure.data.tables.models.TableItem; +import com.azure.data.tables.models.TableStorageException; + +import java.util.Map; + +/** + * WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS ARE USED TO EXTRACT + * APPROPRIATE CODE SEGMENTS FROM THIS FILE. ADD NEW CODE AT THE BOTTOM TO AVOID CHANGING LINE NUMBERS OF EXISTING CODE + * SAMPLES. + * + * Class containing code snippets that will be injected to README.md. + */ +public class ReadmeSamples { + private final String partitionKey = ""; + private final String rowKey = ""; + private final String tableName = ""; + private final TableServiceClient tableServiceClient = new TableServiceClient(null); + private final TableClient tableClient = new TableClient(null); + private final TableEntity entity = new TableEntity(partitionKey, rowKey); + + /** + * Code sample for authenticating with a connection string. + */ + public void authenticateWithConnectionString() { + TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .connectionString("") + .buildClient(); + } + + /** + * Code sample for authenticating with a shared key. + */ + public void authenticateWithSharedKey() { + TablesSharedKeyCredential credential = new TablesSharedKeyCredential("", ""); + TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .endpoint("") + .credential(credential) + .buildClient(); + } + + /** + * Code sample for authenticating with a SAS. + */ + public void authenticateWithSAS() { + TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .endpoint("") + .sasToken("") + .buildClient(); + } + + /** + * Code sample for constructing a service client. + */ + public void constructServiceClient() { + TableServiceClient tableServiceClient = new TableServiceClientBuilder() + .connectionString("") // or use any of the other authentication methods + .buildClient(); + } + + /** + * Code sample for creating a table. + * @throws TableStorageException if the table exists. + */ + public void createTable() { + tableServiceClient.createTable(tableName); + } + + /** + * Code sample for creating a table if it doesn't exist. + */ + public void createTableIfNotExists() { + tableServiceClient.createTableIfNotExists(tableName); + } + + /** + * Code sample for listing tables. + */ + public void listTables() { + ListTablesOptions options = new ListTablesOptions() + .setFilter(String.format("TableName eq '%s'", tableName)); + + for (TableItem tableItem : tableServiceClient.listTables(options)) { + System.out.println(tableItem.getName()); + } + } + + /** + * Code sample for deleting a table. + */ + public void deleteTable() { + tableServiceClient.deleteTable(tableName); + } + + /** + * Code sample for constructing a table client. + */ + public void constructTableClient() { + TableClient tableClient = new TableClientBuilder() + .connectionString("") // or use any of the other authentication methods + .tableName(tableName) + .buildClient(); + } + + /** + * Code sample for retrieving a table client from a service client. + */ + public void retrieveTableClient() { + TableClient tableClient = tableServiceClient.getTableClient(tableName); + } + + /** + * Code sample for creating an entity. + * @throws TableStorageException if the entity exists. + */ + public void createEntity() { + TableEntity entity = new TableEntity(partitionKey, rowKey) + .addProperty("Product", "Marker Set") + .addProperty("Price", 5.00) + .addProperty("Quantity", 21); + + tableClient.createEntity(entity); + } + + /** + * Code sample for listing entities. + */ + public void listEntities() { + ListEntitiesOptions options = new ListEntitiesOptions() + .setFilter(String.format("PartitionKey eq '%s'", partitionKey)) + .setSelect("Product, Price"); + + for (TableEntity entity : tableClient.listEntities(options)) { + Map properties = entity.getProperties(); + System.out.println(String.format("%s: %.2f", properties.get("Product"), properties.get("Price"))); + } + } + + /** + * Code sample for deleting an entity. + */ + public void deleteEntity() { + tableClient.deleteEntity(partitionKey, rowKey); + } + + /** + * Code sample for accessing information about an error. + */ + public void accessErrorInfo() { + // Create the table if it doesn't already exist. + tableServiceClient.createTableIfNotExists(tableName); + + // Now attempt to create the same table unconditionally. + try { + tableServiceClient.createTable(tableName); + } catch (TableStorageException e) { + System.out.println(e.getStatusCode()); // 409 + } + } +}