Fixed snippets and added one combined example.

Also adjusted READMEs accordingly.

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<DnsRecord> 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);
 ```
 

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<DnsRecord> records = zone.nameServers();
-for(DnsRecord record : records) {
-  System.out.println(record)
+List<String> 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,16 +242,16 @@ Then add the following code to list all your zones and DNS records.
 
 ```java
 // List all your zones
-Iterator<Zone> projectZones = dns.listZones().iterateAll();
+Iterator<Zone> 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
-Iterator<DnsRecord> recordIterator = zone.list().iterateAll();
-System.out.println(String.format("DNS records inside %s:", zone.name());
+Iterator<DnsRecord> 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<ChangeRequest> 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.
 

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);
   }
 }

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());
   }
 }

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<DnsRecord> recordIterator = dns.listDnsRecords(zoneName).iterateAll();