Skip to content

Commit

Permalink
Renamed DnsRecord to RecordSet. Fixes googleapis#779.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mderka
mderka committed Mar 24, 2016
1 parent 2f90e7e commit 1a5aade
Show file tree
Hide file tree
Showing 26 changed files with 477 additions and 470 deletions.
12 changes: 6 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -249,13 +249,13 @@ ZoneInfo zoneInfo = ZoneInfo.of(zoneName, domainName, description);
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).
The second snippet shows how to create records inside a zone. The complete code can be found on [CreateOrUpdateRecordSets.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateRecordSets.java).
```java
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.RecordSet;
import com.google.gcloud.dns.Zone;
import java.util.Iterator;
Expand All @@ -265,17 +265,17 @@ Dns dns = DnsOptions.defaultInstance().service();
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)
RecordSet toCreate = RecordSet.builder("www.someexampledomain.com.", RecordSet.Type.A)
.ttl(24, TimeUnit.HOURS)
.addRecord(ip)
.build();
ChangeRequest.Builder changeBuilder = ChangeRequest.builder().add(toCreate);
// 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();
Iterator<RecordSet> recordSetIterator = zone.listRecordSets().iterateAll();
while (recordSetIterator.hasNext()) {
RecordSet current = recordSetIterator.next();
if (toCreate.name().equals(current.name()) &&
toCreate.type().equals(current.type())) {
changeBuilder.delete(current);
Expand Down
70 changes: 35 additions & 35 deletions gcloud-java-dns/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,15 +92,15 @@ Dns dns = DnsOptions.defaultInstance().service();
For other authentication options, see the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) page.

#### Managing Zones
DNS records in `gcloud-java-dns` are managed inside containers called "zones". `ZoneInfo` is a class
Record sets in `gcloud-java-dns` are managed inside containers called "zones". `ZoneInfo` is a class
which encapsulates metadata that describe a zone in Google Cloud DNS. `Zone`, a subclass of `ZoneInfo`, adds service-related
functionality over `ZoneInfo`.

*Important: Zone names 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).*

In this code snippet, we create a new zone to manage DNS records for domain `someexampledomain.com.`
In this code snippet, we create a new zone to manage record sets for domain `someexampledomain.com.`

*Important: The service may require that you verify ownership of the domain for which you are creating a zone.
Hence, we recommend that you do so beforehand. You can verify ownership of
Expand Down Expand Up @@ -128,8 +128,8 @@ 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
You now have an empty zone hosted in Google Cloud DNS which is ready to be populated with
record sets for domain name `someexampledomain.com.` Upon creating the zone, the cloud service
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. First, import
Expand All @@ -152,25 +152,25 @@ You can now instruct your domain registrar to [update your domain name servers]
As soon as this happens and the change propagates through cached values in DNS resolvers,
all the DNS queries will be directed to and answered by the Google Cloud DNS service.

#### Creating DNS Records
Now that we have a zone, we can add some DNS records. The DNS records held within zones are
#### Creating Record Sets
Now that we have a zone, we can add some record sets. The record sets held within zones are
modified by "change requests". In this example, we create and apply a change request to
our zone that creates a DNS record of type A and points URL www.someexampledomain.com to
our zone that creates a record set of type A and points URL www.someexampledomain.com to
IP address 12.13.14.15. Start by adding

```java
import com.google.gcloud.dns.ChangeRequest;
import com.google.gcloud.dns.DnsRecord;
import com.google.gcloud.dns.RecordSet;

import java.util.concurrent.TimeUnit;
```

and proceed with:

```java
// Prepare a www.someexampledomain.com. type A record with ttl of 24 hours
// Prepare a www.someexampledomain.com. type A record set with ttl of 24 hours
String ip = "12.13.14.15";
DnsRecord toCreate = DnsRecord.builder("www.someexampledomain.com.", DnsRecord.Type.A)
RecordSet toCreate = RecordSet.builder("www." + zone.dnsName(), RecordSet.Type.A)
.ttl(24, TimeUnit.HOURS)
.addRecord(ip)
.build();
Expand All @@ -182,12 +182,12 @@ ChangeRequest changeRequest = ChangeRequest.builder().add(toCreate).build();
changeRequest = zone.applyChangeRequest(changeRequest);
```

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).
The `addRecord` method of `RecordSet.Builder` accepts records in the form of
strings. The format of the strings depends on the type of the record sets to be added.
More information on the supported record set 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
If you already have a record set, Cloud DNS will return an error upon an attempt to create a duplicate of it.
You can modify the code above to create a record set or update it if it already exists by making the
following adjustment in your imports

```java
Expand All @@ -202,9 +202,9 @@ 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<DnsRecord> recordIterator = zone.listDnsRecords().iterateAll();
while (recordIterator.hasNext()) {
DnsRecord current = recordIterator.next();
Iterator<RecordSet> recordSetIterator = zone.listRecordSets().iterateAll();
while (recordSetIterator.hasNext()) {
RecordSet current = recordSetIterator.next();
if (toCreate.name().equals(current.name()) && toCreate.type().equals(current.type())) {
changeBuilder.delete(current);
}
Expand Down Expand Up @@ -235,15 +235,15 @@ Change requests are applied atomically to all the assigned DNS servers at once.
happens, it may still take a while for the change to be registered by the DNS cache resolvers.
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.
#### Listing Zones and Record Sets
Suppose that you have added more zones and record sets, and now you want to list them.
First, import the following (unless you have done so in the previous section):

```java
import java.util.Iterator;
```

Then add the following code to list all your zones and DNS records.
Then add the following code to list all your zones and record sets.

```java
// List all your zones
Expand All @@ -254,11 +254,11 @@ while (zoneIterator.hasNext()) {
counter++;
}

// List the DNS records in a particular zone
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());
// List the record sets in a particular zone
recordSetIterator = zone.listRecordSets().iterateAll();
System.out.println(String.format("Record sets inside %s:", zone.name()));
while (recordSetIterator.hasNext()) {
System.out.println(recordSetIterator.next());
}
```

Expand All @@ -276,15 +276,15 @@ while (changeIterator.hasNext()) {
#### Deleting Zones

If you no longer want to host a zone in Cloud DNS, you can delete it.
First, you need to empty the zone by deleting all its records except for the default SOA and NS records.
First, you need to empty the zone by deleting all its records except for the default SOA and NS record sets.

```java
// Make a change for deleting the records
ChangeRequest.Builder changeBuilder = ChangeRequest.builder();
// Make a change for deleting the record sets
changeBuilder = ChangeRequest.builder();
while (recordIterator.hasNext()) {
DnsRecord current = recordIterator.next();
RecordSet current = recordIterator.next();
// SOA and NS records cannot be deleted
if (!DnsRecord.Type.SOA.equals(current.type()) && !DnsRecord.Type.NS.equals(current.type())) {
if (!RecordSet.Type.SOA.equals(current.type()) && !RecordSet.Type.NS.equals(current.type())) {
changeBuilder.delete(current);
}
}
Expand Down Expand Up @@ -324,11 +324,11 @@ if (result) {

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/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
we create a zone. In [CreateOrUpdateRecordSets.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/CreateOrUpdateRecordSets.java)
we create a type A record set for a zone, or update an existing type A record set to a new IP address. We
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
Finally, in [ManipulateZonesAndRecordSets.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/dns/snippets/ManipulateZonesAndRecordSets.java)
we assemble all the code snippets together and create zone, create or update a record set, list zones, list record sets, list changes, and
delete a zone. The applications assume that they are running on Compute Engine or from your own desktop. To run any of these examples 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.
Expand Down
62 changes: 31 additions & 31 deletions gcloud-java-dns/src/main/java/com/google/gcloud/dns/ChangeRequest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
import java.util.Objects;

/**
* A class representing an atomic update to a collection of {@link DnsRecord}s within a {@code
* A class representing an atomic update to a collection of {@link RecordSet}s within a {@code
* Zone}.
*
* @see <a href="https://cloud.google.com/dns/api/v1/changes">Google Cloud DNS documentation</a>
Expand All @@ -48,8 +48,8 @@ public ChangeRequest apply(com.google.api.services.dns.model.Change pb) {
}
};
private static final long serialVersionUID = -9027378042756366333L;
private final List<DnsRecord> additions;
private final List<DnsRecord> deletions;
private final List<RecordSet> additions;
private final List<RecordSet> deletions;
private final String id;
private final Long startTimeMillis;
private final Status status;
Expand All @@ -70,8 +70,8 @@ public enum Status {
*/
public static class Builder {

private List<DnsRecord> additions = new LinkedList<>();
private List<DnsRecord> deletions = new LinkedList<>();
private List<RecordSet> additions = new LinkedList<>();
private List<RecordSet> deletions = new LinkedList<>();
private String id;
private Long startTimeMillis;
private Status status;
Expand All @@ -88,43 +88,43 @@ private Builder() {
}

/**
* Sets a collection of {@link DnsRecord}s which are to be added to the zone upon executing this
* Sets a collection of {@link RecordSet}s which are to be added to the zone upon executing this
* {@code ChangeRequest}.
*/
public Builder additions(List<DnsRecord> additions) {
public Builder additions(List<RecordSet> additions) {
this.additions = Lists.newLinkedList(checkNotNull(additions));
return this;
}

/**
* Sets a collection of {@link DnsRecord}s which are to be deleted from the zone upon executing
* Sets a collection of {@link RecordSet}s which are to be deleted from the zone upon executing
* this {@code ChangeRequest}.
*/
public Builder deletions(List<DnsRecord> deletions) {
public Builder deletions(List<RecordSet> deletions) {
this.deletions = Lists.newLinkedList(checkNotNull(deletions));
return this;
}

/**
* Adds a {@link DnsRecord} to be <strong>added</strong> to the zone upon executing this {@code
* Adds a {@link RecordSet} to be <strong>added</strong> to the zone upon executing this {@code
* ChangeRequest}.
*/
public Builder add(DnsRecord record) {
this.additions.add(checkNotNull(record));
public Builder add(RecordSet recordSet) {
this.additions.add(checkNotNull(recordSet));
return this;
}

/**
* Adds a {@link DnsRecord} to be <strong>deleted</strong> to the zone upon executing this
* Adds a {@link RecordSet} to be <strong>deleted</strong> to the zone upon executing this
* {@code ChangeRequest}.
*/
public Builder delete(DnsRecord record) {
this.deletions.add(checkNotNull(record));
public Builder delete(RecordSet recordSet) {
this.deletions.add(checkNotNull(recordSet));
return this;
}

/**
* Clears the collection of {@link DnsRecord}s which are to be added to the zone upon executing
* Clears the collection of {@link RecordSet}s which are to be added to the zone upon executing
* this {@code ChangeRequest}.
*/
public Builder clearAdditions() {
Expand All @@ -133,7 +133,7 @@ public Builder clearAdditions() {
}

/**
* Clears the collection of {@link DnsRecord}s which are to be deleted from the zone upon
* Clears the collection of {@link RecordSet}s which are to be deleted from the zone upon
* executing this {@code ChangeRequest}.
*/
public Builder clearDeletions() {
Expand All @@ -142,20 +142,20 @@ public Builder clearDeletions() {
}

/**
* Removes a single {@link DnsRecord} from the collection of records to be
* Removes a single {@link RecordSet} from the collection of records to be
* <strong>added</strong> to the zone upon executing this {@code ChangeRequest}.
*/
public Builder removeAddition(DnsRecord record) {
this.additions.remove(record);
public Builder removeAddition(RecordSet recordSet) {
this.additions.remove(recordSet);
return this;
}

/**
* Removes a single {@link DnsRecord} from the collection of records to be
* Removes a single {@link RecordSet} from the collection of records to be
* <strong>deleted</strong> from the zone upon executing this {@code ChangeRequest}.
*/
public Builder removeDeletion(DnsRecord record) {
this.deletions.remove(record);
public Builder removeDeletion(RecordSet recordSet) {
this.deletions.remove(recordSet);
return this;
}

Expand Down Expand Up @@ -215,18 +215,18 @@ public Builder toBuilder() {
}

/**
* Returns the list of {@link DnsRecord}s to be added to the zone upon submitting this {@code
* Returns the list of {@link RecordSet}s to be added to the zone upon submitting this {@code
* ChangeRequest}.
*/
public List<DnsRecord> additions() {
public List<RecordSet> additions() {
return additions;
}

/**
* Returns the list of {@link DnsRecord}s to be deleted from the zone upon submitting this {@code
* Returns the list of {@link RecordSet}s to be deleted from the zone upon submitting this {@code
* ChangeRequest}.
*/
public List<DnsRecord> deletions() {
public List<RecordSet> deletions() {
return deletions;
}

Expand Down Expand Up @@ -267,9 +267,9 @@ com.google.api.services.dns.model.Change toPb() {
pb.setStatus(status().name().toLowerCase());
}
// set a list of additions
pb.setAdditions(Lists.transform(additions(), DnsRecord.TO_PB_FUNCTION));
pb.setAdditions(Lists.transform(additions(), RecordSet.TO_PB_FUNCTION));
// set a list of deletions
pb.setDeletions(Lists.transform(deletions(), DnsRecord.TO_PB_FUNCTION));
pb.setDeletions(Lists.transform(deletions(), RecordSet.TO_PB_FUNCTION));
return pb;
}

Expand All @@ -286,10 +286,10 @@ static ChangeRequest fromPb(com.google.api.services.dns.model.Change pb) {
builder.status(ChangeRequest.Status.valueOf(pb.getStatus().toUpperCase()));
}
if (pb.getDeletions() != null) {
builder.deletions(Lists.transform(pb.getDeletions(), DnsRecord.FROM_PB_FUNCTION));
builder.deletions(Lists.transform(pb.getDeletions(), RecordSet.FROM_PB_FUNCTION));
}
if (pb.getAdditions() != null) {
builder.additions(Lists.transform(pb.getAdditions(), DnsRecord.FROM_PB_FUNCTION));
builder.additions(Lists.transform(pb.getAdditions(), RecordSet.FROM_PB_FUNCTION));
}
return builder.build();
}
Expand Down
Loading

0 comments on commit 1a5aade

Please sign in to comment.