From 485700d5c0c0711a99b15cdbc039c897e9145f7f Mon Sep 17 00:00:00 2001 From: Martin Derka Date: Wed, 16 Mar 2016 09:36:17 -0700 Subject: [PATCH] Fixed snippets and added one combined example. Also adjusted READMEs accordingly. --- README.md | 24 +++- gcloud-java-dns/README.md | 73 +++++----- .../snippets/CreateOrUpdateDnsRecords.java | 5 +- .../examples/dns/snippets/CreateZone.java | 6 +- .../examples/dns/snippets/DeleteZone.java | 2 +- .../examples/dns/snippets/ListDnsRecords.java | 54 ------- .../examples/dns/snippets/ListZones.java | 51 ------- .../snippets/ManipulateZonesAndRecords.java | 135 ++++++++++++++++++ 8 files changed, 200 insertions(+), 150 deletions(-) delete mode 100644 gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListDnsRecords.java delete mode 100644 gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListZones.java create mode 100644 gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecords.java diff --git a/README.md b/README.md index 6ee147a460ed..786a28824e3d 100644 --- a/README.md +++ b/README.md @@ -242,11 +242,11 @@ import com.google.gcloud.dns.Zone; import com.google.gcloud.dns.ZoneInfo; Dns dns = DnsOptions.defaultInstance().service(); -String zoneName = "my_unique_zone"; +String zoneName = "my-unique-zone"; String domainName = "someexampledomain.com."; String description = "This is a gcloud-java-dns sample zone."; ZoneInfo zoneInfo = ZoneInfo.of(zoneName, domainName, description); -Zone createdZone = dns.create(zoneInfo); +Zone zone = dns.create(zoneInfo); ``` The second snippet shows how to create records inside a zone. The complete code can be found on [CreateOrUpdateDnsRecords.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java). @@ -262,14 +262,26 @@ import java.util.Iterator; import java.util.concurrent.TimeUnit; Dns dns = DnsOptions.defaultInstance().service(); -String zoneName = "some-sample-zone"; +String zoneName = "my-unique-zone"; Zone zone = dns.getZone(zoneName); String ip = "12.13.14.15"; DnsRecord toCreate = DnsRecord.builder("www.someexampledomain.com.", DnsRecord.Type.A) - .ttl(24, TimeUnit.HOURS) - .addRecord(ip) - .build(); + .ttl(24, TimeUnit.HOURS) + .addRecord(ip) + .build(); ChangeRequest changeRequest = ChangeRequest.builder().add(toCreate).build(); + +// Verify that the record does not exist yet. +// If it does exist, we will overwrite it with our prepared record. +Iterator recordIterator = zone.listDnsRecords().iterateAll(); +while (recordIterator.hasNext()) { + DnsRecord current = recordIterator.next(); + if (toCreate.name().equals(current.name()) && + toCreate.type().equals(current.type())) { + changeBuilder.delete(current); + } +} + zone.applyChangeRequest(changeRequest); ``` diff --git a/gcloud-java-dns/README.md b/gcloud-java-dns/README.md index 6d7b16b057c2..b07ebca35558 100644 --- a/gcloud-java-dns/README.md +++ b/gcloud-java-dns/README.md @@ -98,7 +98,7 @@ functionality over `ZoneInfo`. *Important: Zone must be unique to the project. If you choose a zone name that already exists within your project, you'll get a helpful error message telling you to choose another name. In the code below, -replace "my_unique_zone" with a unique zone name. See more about naming rules [here](https://cloud.google.com/dns/api/v1/managedZones#name).* +replace "my-unique-zone" with a unique zone name. See more about naming rules [here](https://cloud.google.com/dns/api/v1/managedZones#name).* In this code snippet, we create a new zone in which we intend to manage DNS record for domain `someexampledomain.com.` @@ -119,33 +119,27 @@ Then add the following code to create a zone. ```java // Create a zone metadata object -String zoneName = "my_unique_zone"; // Change this zone name which is unique within your project +String zoneName = "my-unique-zone"; // Change this zone name which is unique within your project String domainName = "someexampledomain.com."; // Change this to a domain which you own String description = "This is a gcloud-java-dns sample zone."; ZoneInfo zoneInfo = ZoneInfo.of(zoneName, domainName, description); // Create zone in Google Cloud DNS -Zone createdZone = dns.create(zoneInfo); -System.out.printf("Zone was created and assigned ID %s.%n", createdZone.id()); +Zone zone = dns.create(zoneInfo); +System.out.printf("Zone was created and assigned ID %s.%n", zone.id()); ``` You now have an empty zone hosted in Google Cloud DNS which is ready to be populated with DNS records for domain name `someexampledomain.com.` Upon creating the zone, the cloud service -automatically assigned a set of DNS servers to host records for this zone, and -created the required SOA and NS records for the domain. The following snippet reads and prints the list of assigned servers. -You will need to add the following import to your code: - -```java -import com.google.gcloud.dns.DnsRecord -``` - -and proceed with: +assigned a set of DNS servers to host records for this zone and +created the required SOA and NS records for the domain. The following snippet prints the list of servers +assigned to the zone created above. ```java // Print assigned name servers -List records = zone.nameServers(); -for(DnsRecord record : records) { - System.out.println(record) +List nameServers = zone.nameServers(); +for(String nameServer : nameServers) { + System.out.println(nameServer); } ``` @@ -160,7 +154,10 @@ our zone that creates a DNS record of type A and points URL www.someexampledomai IP address 12.13.14.15. Start by adding ```java -import com.google.gcloud.dns.ChangeRequest +import com.google.gcloud.dns.ChangeRequest; +import com.google.gcloud.dns.DnsRecord; + +import java.util.concurrent.TimeUnit; ``` and proceed with: @@ -177,16 +174,22 @@ DnsRecord toCreate = DnsRecord.builder("www.someexampledomain.com.", DnsRecord.T ChangeRequest changeRequest = ChangeRequest.builder().add(toCreate).build(); // Build and apply the change request to our zone -changeRequest = zone.applyChangeRequest(); +changeRequest = zone.applyChangeRequest(changeRequest); ``` -The `addRecord` function of `DnsRecord.Builder` accepts records in the form of +The `addRecord` method of `DnsRecord.Builder` accepts records in the form of strings. The format of the strings depends on the type of the DNS record to be added. More information on the supported DNS record types and record formats can be found [here](https://cloud.google.com/dns/what-is-cloud-dns#supported_record_types). If you already have a DNS record, Cloud DNS will return an error upon an attempt to create a duplicate of it. You can modify the code above to create a DNS record or update it if it already exists by making the -following adjustment: +following adjustment in your imports + +```java +import java.util.Iterator; +``` + +and in the code ```java // Make a change @@ -203,7 +206,8 @@ while (recordIterator.hasNext()) { } // Build and apply the change request to our zone -zone.applyChangeRequest(changeBuilder.build()); +ChangeRequest changeRequest = changeBuilder.build(); +zone.applyChangeRequest(changeRequest); ``` You can find more information about changes in the [Cloud DNS documentation] (https://cloud.google.com/dns/what-is-cloud-dns#cloud_dns_api_concepts). @@ -212,7 +216,11 @@ can wait for its completion as follows: ```java while (ChangeRequest.Status.PENDING.equals(changeRequest.status())) { - Thread.sleep(500L); + try { + Thread.sleep(500L); + } catch (InterruptedException e) { + System.err.println("The thread was interrupted while waiting..."); + } changeRequest = dns.getChangeRequest(zone.name(), changeRequest.id()); } System.out.println("The change request has been applied."); @@ -224,7 +232,7 @@ See more on this topic [here](https://cloud.google.com/dns/monitoring). #### Listing Zones and DNS Records Suppose that you have added more zones and DNS records, and now you want to list them. -First, import the following: +First, import the following (unless you have done so in the previous section): ```java import java.util.Iterator; @@ -234,7 +242,7 @@ Then add the following code to list all your zones and DNS records. ```java // List all your zones -Iterator projectZones = dns.listZones().iterateAll(); +Iterator zoneIterator = dns.listZones().iterateAll(); int counter = 1; while (zoneIterator.hasNext()) { System.out.printf("#%d.: %s%n%n", counter, zoneIterator.next()); @@ -242,8 +250,8 @@ while (zoneIterator.hasNext()) { } // List the DNS records in a particular zone -Iterator recordIterator = zone.list().iterateAll(); -System.out.println(String.format("DNS records inside %s:", zone.name()); +Iterator recordIterator = zone.listDnsRecords().iterateAll(); +System.out.println(String.format("DNS records inside %s:", zone.name())); while (recordIterator.hasNext()) { System.out.println(recordIterator.next()); } @@ -254,7 +262,7 @@ You can also list the history of change requests that were applied to a zone: ```java // List the change requests applied to a particular zone Iterator changeIterator = zone.listChangeRequests().iterateAll(); -System.out.println(String.format("The history of changes in %s:", zone.name()); +System.out.println(String.format("The history of changes in %s:", zone.name())); while (changeIterator.hasNext()) { System.out.println(changeIterator.next()); } @@ -310,14 +318,13 @@ if (result) { #### Complete Source Code We composed some of the aforementioned snippets into complete executable code samples. In -[CreateZones.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateAndListZones.java) +[CreateZones.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateZone.java) we create a zone. In [CreateOrUpdateDnsRecords.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java) we create a type A record for a zone, or update an existing type A record to a new IP address. We -demonstrate how to list all zones in your project in [ListZones.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListZones.java) -and how to list DNS records within a zone in [ListDnsRecords.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListDnsRecords.java). -Finally, in [DeleteZone.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java) -we list and delete all the records within a zone, and then delete the zone itself. The applications -assume that they are running on Compute Engine or from your own desktop. To run the example on App +demonstrate how to delete a zone in [DeleteZone.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java). +Finally, in [ManipulateZonesAndRecords.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecords.java) +we assemble all the code snippets together and create zone, create or update a DNS record, list zones, list DNS records, list changes, and +delete a zone. The applications assume that they are running on Compute Engine or from your own desktop. To run the example on App Engine, simply move the code from the main method to your application's servlet class and change the print statements to display on your webpage. diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java index 34c668fe17e7..71327ba98a96 100644 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java +++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateDnsRecords.java @@ -42,7 +42,7 @@ public static void main(String... args) { Dns dns = DnsOptions.defaultInstance().service(); // Change this to a zone name that exists within your project - String zoneName = "my_unique_zone"; + String zoneName = "my-unique-zone"; // Get zone from the service Zone zone = dns.getZone(zoneName); @@ -68,6 +68,7 @@ public static void main(String... args) { } // Build and apply the change request to our zone - zone.applyChangeRequest(changeBuilder.build()); + ChangeRequest changeRequest = changeBuilder.build(); + zone.applyChangeRequest(changeRequest); } } diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateZone.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateZone.java index d67120380b36..2c2ba211bd86 100644 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateZone.java +++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateZone.java @@ -39,13 +39,13 @@ public static void main(String... args) { Dns dns = DnsOptions.defaultInstance().service(); // Create a zone metadata object - String zoneName = "my_unique_zone"; // Change this zone name which is unique within your project + String zoneName = "my-unique-zone"; // Change this zone name which is unique within your project String domainName = "someexampledomain.com."; // Change this to a domain which you own String description = "This is a gcloud-java-dns sample zone."; ZoneInfo zoneInfo = ZoneInfo.of(zoneName, domainName, description); // Create zone in Google Cloud DNS - Zone createdZone = dns.create(zoneInfo); - System.out.printf("Zone was created and assigned ID %s.%n", createdZone.id()); + Zone zone = dns.create(zoneInfo); + System.out.printf("Zone was created and assigned ID %s.%n", zone.id()); } } diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java index adc357b65aeb..e841a4cd54ed 100644 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java +++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/DeleteZone.java @@ -41,7 +41,7 @@ public static void main(String... args) { Dns dns = DnsOptions.defaultInstance().service(); // Change this to a zone name that exists within your project and that you want to delete. - String zoneName = "my_unique_zone"; + String zoneName = "my-unique-zone"; // Get iterator for the existing records which have to be deleted before deleting the zone Iterator recordIterator = dns.listDnsRecords(zoneName).iterateAll(); diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListDnsRecords.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListDnsRecords.java deleted file mode 100644 index 496657ebcf22..000000000000 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListDnsRecords.java +++ /dev/null @@ -1,54 +0,0 @@ -/* - * Copyright 2016 Google Inc. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* - * EDITING INSTRUCTIONS - * This file is referenced in README's and javadoc. Any change to this file should be reflected in - * the project's README's and package-info.java. - */ - -package com.google.gcloud.examples.dns.snippets; - -import com.google.gcloud.dns.Dns; -import com.google.gcloud.dns.DnsOptions; -import com.google.gcloud.dns.DnsRecord; -import com.google.gcloud.dns.Zone; - -import java.util.Iterator; - -/** - * A snippet for Google Cloud DNS showing how to create list DNS records. - */ -public class ListDnsRecords { - - public static void main(String... args) { - // Create a service object. - // The project ID and credentials will be inferred from the environment. - Dns dns = DnsOptions.defaultInstance().service(); - - // Change this to a zone name that exists within your project - String zoneName = "my_unique_zone"; - - // Get zone from the service - Zone zone = dns.getZone(zoneName); - - // List and print DNS records - Iterator recordIterator = zone.listDnsRecords().iterateAll(); - while (recordIterator.hasNext()) { - System.out.println(recordIterator.next()); - } - } -} diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListZones.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListZones.java deleted file mode 100644 index 1a624d52cec6..000000000000 --- a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ListZones.java +++ /dev/null @@ -1,51 +0,0 @@ -/* - * Copyright 2016 Google Inc. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* - * EDITING INSTRUCTIONS - * This file is referenced in README's and javadoc. Any change to this file should be reflected in - * the project's README's and package-info.java. - */ - -package com.google.gcloud.examples.dns.snippets; - -import com.google.gcloud.dns.Dns; -import com.google.gcloud.dns.DnsOptions; -import com.google.gcloud.dns.Zone; - -import java.util.Iterator; - -/** - * A snippet for Google Cloud DNS showing how to list all zones in the project. You will need to - * change the {@code domainName} to a domain name, the ownership of which you should verify with - * Google. - */ -public class ListZones { - - public static void main(String... args) { - // Create a service object - // The project ID and credentials will be inferred from the environment. - Dns dns = DnsOptions.defaultInstance().service(); - - // List all the zones within this project - Iterator zoneIterator = dns.listZones().iterateAll(); - int counter = 1; - while (zoneIterator.hasNext()) { - System.out.printf("#%d.: %s%n%n", counter, zoneIterator.next()); - counter++; - } - } -} diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecords.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecords.java new file mode 100644 index 000000000000..09bcb4b92dd6 --- /dev/null +++ b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecords.java @@ -0,0 +1,135 @@ +package com.google.gcloud.examples.dns.snippets; + +import com.google.gcloud.dns.ChangeRequest; +import com.google.gcloud.dns.Dns; +import com.google.gcloud.dns.DnsOptions; +import com.google.gcloud.dns.DnsRecord; +import com.google.gcloud.dns.Zone; +import com.google.gcloud.dns.ZoneInfo; + +import java.util.Iterator; +import java.util.List; +import java.util.concurrent.TimeUnit; + +/** + * A complete snippet for Google Cloud DNS showing how to create and delete a zone. It also shows + * how to create, list and delete DNS records, and how to list changes. + */ +public class ManipulateZonesAndRecords { + + public static void main(String... args) { + Dns dns = DnsOptions.defaultInstance().service(); + + // Create a zone metadata object + String zoneName = "my-unique-zone"; // Change this zone name which is unique within your project + String domainName = "someexampledomain.com."; // Change this to a domain which you own + String description = "This is a gcloud-java-dns sample zone."; + ZoneInfo zoneInfo = ZoneInfo.of(zoneName, domainName, description); + + // Create zone in Google Cloud DNS + Zone zone = dns.create(zoneInfo); + System.out.printf("Zone was created and assigned ID %s.%n", zone.id()); + + // Print assigned name servers + List nameServers = zone.nameServers(); + for (String nameServer : nameServers) { + System.out.println(nameServer); + } + + // Prepare a www.someexampledomain.com. type A record with ttl of 24 hours + String ip = "12.13.14.15"; + DnsRecord toCreate = DnsRecord.builder("www.someexampledomain.com.", DnsRecord.Type.A) + .ttl(24, TimeUnit.HOURS) + .addRecord(ip) + .build(); + + // Make a change + ChangeRequest.Builder changeBuilder = ChangeRequest.builder().add(toCreate); + + // Verify the type A record does not exist yet. + // If it does exist, we will overwrite it with our prepared record. + Iterator recordIterator = zone.listDnsRecords().iterateAll(); + while (recordIterator.hasNext()) { + DnsRecord current = recordIterator.next(); + if (toCreate.name().equals(current.name()) && toCreate.type().equals(current.type())) { + changeBuilder.delete(current); + } + } + + // Build and apply the change request to our zone + ChangeRequest changeRequest = changeBuilder.build(); + zone.applyChangeRequest(changeRequest); + + while (ChangeRequest.Status.PENDING.equals(changeRequest.status())) { + try { + Thread.sleep(500L); + } catch (InterruptedException e) { + System.err.println("The thread was interrupted while waiting..."); + } + changeRequest = dns.getChangeRequest(zone.name(), changeRequest.id()); + } + System.out.println("The change request has been applied."); + + // List all your zones + Iterator zoneIterator = dns.listZones().iterateAll(); + int counter = 1; + while (zoneIterator.hasNext()) { + System.out.printf("#%d.: %s%n%n", counter, zoneIterator.next()); + counter++; + } + + // List the DNS records in a particular zone + recordIterator = zone.listDnsRecords().iterateAll(); + System.out.println(String.format("DNS records inside %s:", zone.name())); + while (recordIterator.hasNext()) { + System.out.println(recordIterator.next()); + } + + // List the change requests applied to a particular zone + Iterator changeIterator = zone.listChangeRequests().iterateAll(); + System.out.println(String.format("The history of changes in %s:", zone.name())); + while (changeIterator.hasNext()) { + System.out.println(changeIterator.next()); + } + + // Make a change for deleting the records + changeBuilder = ChangeRequest.builder(); + while (recordIterator.hasNext()) { + DnsRecord current = recordIterator.next(); + // SOA and NS records cannot be deleted + if (!DnsRecord.Type.SOA.equals(current.type()) && !DnsRecord.Type.NS.equals(current.type())) { + changeBuilder.delete(current); + } + } + + // Build and apply the change request to our zone if it contains records to delete + changeRequest = changeBuilder.build(); + if (!changeRequest.deletions().isEmpty()) { + changeRequest = dns.applyChangeRequest(zoneName, changeRequest); + + // Wait for change to finish, but save data traffic by transferring only ID and status + Dns.ChangeRequestOption option = + Dns.ChangeRequestOption.fields(Dns.ChangeRequestField.STATUS); + while (ChangeRequest.Status.PENDING.equals(changeRequest.status())) { + System.out.println("Waiting for change to complete. Going to sleep for 500ms..."); + try { + Thread.sleep(500); + } catch (InterruptedException e) { + System.err.println("The thread was interrupted while waiting for change request to be " + + "processed."); + } + + // Update the change, but fetch only change ID and status + changeRequest = dns.getChangeRequest(zoneName, changeRequest.id(), option); + } + } + + // Delete the zone + boolean result = dns.delete(zoneName); + if (result) { + System.out.println("Zone was deleted."); + } else { + System.out.println("Zone was not deleted because it does not exist."); + } + } +}