|
| 1 | +/*! |
| 2 | + |
| 3 | +@page migrating-from-dataclient Migrating from `DataClient` to `DataConnection` |
| 4 | + |
| 5 | +In this document we describe how to migrate existing code that uses `DataClient` |
| 6 | +to use `DataConnection`. |
| 7 | + |
| 8 | +All examples use the following aliases: |
| 9 | + |
| 10 | +```{.cc} |
| 11 | +namespace gc = ::google::cloud; |
| 12 | +namespace cbt = ::google::cloud::bigtable; |
| 13 | +``` |
| 14 | + |
| 15 | +## Simple case |
| 16 | + |
| 17 | +```{.cc} |
| 18 | +cbt::Table OldCode() { |
| 19 | + auto data_client = cbt::MakeDataClient("project-id", "instance-id"); |
| 20 | + return cbt::Table(data_client, "table-id"); |
| 21 | +} |
| 22 | + |
| 23 | +cbt::Table UpdatedCode() { |
| 24 | + auto connection = cbt::MakeDataConnection(); |
| 25 | + return cbt::Table( |
| 26 | + connection, cbt::TableResource("project-id", "instance-id", "table-id")); |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +Note that the `DataConnection` is not associated with any resource ids. They |
| 31 | +are instead packaged as a `TableResource` and passed as a single object to |
| 32 | +`Table`. |
| 33 | + |
| 34 | +## Optional configuration |
| 35 | + |
| 36 | +Note that there is only one `Table` constructor that accepts a |
| 37 | +`DataConnection`. All configuration is done via the `Options` parameter. |
| 38 | + |
| 39 | +### Set an application profile id |
| 40 | + |
| 41 | +```{.cc} |
| 42 | +cbt::Table OldCode() { |
| 43 | + auto data_client = cbt::MakeDataClient("project-id", "instance-id"); |
| 44 | + return cbt::Table(data_client, "app-profile-id", "table-id"); |
| 45 | +} |
| 46 | + |
| 47 | +cbt::Table UpdatedCode() { |
| 48 | + auto connection = cbt::MakeDataConnection(); |
| 49 | + return cbt::Table( |
| 50 | + connection, cbt::TableResource("project-id", "instance-id", "table-id"), |
| 51 | + gc::Options{}.set<cbt::AppProfileIdOption>("app-profile-id")); |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +### Set a custom retry policy |
| 56 | + |
| 57 | +```{.cc} |
| 58 | +cbt::Table OldCode() { |
| 59 | + auto data_client = cbt::MakeDataClient("project-id", "instance-id"); |
| 60 | + return cbt::Table(data_client, "table-id", |
| 61 | + cbt::LimitedErrorCountRetryPolicy(7)); |
| 62 | +} |
| 63 | + |
| 64 | +cbt::Table UpdatedCode() { |
| 65 | + auto connection = cbt::MakeDataConnection(); |
| 66 | + return cbt::Table(connection, |
| 67 | + cbt::TableResource("project-id", "instance-id", "table-id"), |
| 68 | + gc::Options{}.set<cbt::DataRetryPolicyOption>( |
| 69 | + cbt::DataLimitedErrorCountRetryPolicy(7).clone())); |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +The retry, backoff, and idempotency policies are packaged in `Options` as |
| 74 | +`shared_ptr`s, instead of passed by value as variadic parameters to |
| 75 | +`Table(..., Policies&&)`. |
| 76 | + |
| 77 | +Also note that the retry and backoff policy types have changed. If you defined |
| 78 | +your own policy, extending `RPCRetryPolicy` or `RPCBackoffPolicy`, it will not |
| 79 | +be compatible with the new types. The new policies do not have a |
| 80 | +`Setup(grpc::ClientContext&)` function. This function has not been included |
| 81 | +because we believe that setting up the `grpc::ClientContext`... |
| 82 | + 1. Should not be tied to the retry policies. |
| 83 | + 2. Is unlikely to be needed by external customers. |
| 84 | + |
| 85 | +If you do need a `Setup()` feature, please [open a feature request][new-issue] |
| 86 | +explaining your use case, and we will be happy to accommodate you. |
| 87 | + |
| 88 | +[new-issue]: https://github.com/googleapis/google-cloud-cpp/issues/new/choose |
| 89 | + |
| 90 | +*/ |
0 commit comments