Skip to content

Commit e083dfd

Browse files
mderkamderka
committed
Fixed documentation and some code formatting. Declared exceptions to be
thrown when parent objects do not exist. Changed contracts of applyChangeRequest and getChangeRequest methods. Adjusted tests.
1 parent a69101a commit e083dfd

4 files changed

Lines changed: 171 additions & 182 deletions

File tree

‎gcloud-java-dns/src/main/java/com/google/gcloud/dns/Dns.java‎

Lines changed: 72 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ public interface Dns extends Service<DnsOptions> {
3737
* The fields of a project.
3838
*
3939
* <p>These values can be used to specify the fields to include in a partial response when calling
40-
* {@code Dns#getProjectInfo(ProjectGetOption...)}. Project ID is always returned, even if not
40+
* {@link Dns#getProjectInfo(ProjectOption...)}. Project ID is always returned, even if not
4141
* specified.
4242
*/
4343
enum ProjectField {
@@ -69,7 +69,7 @@ static String selector(ProjectField... fields) {
6969
* The fields of a zone.
7070
*
7171
* <p>These values can be used to specify the fields to include in a partial response when calling
72-
* {@code Dns#getZone(BigInteger, ZoneOption...)} or {@code Dns#getZone(String, ZoneOption...)}.
72+
* {@link Dns#getZone(BigInteger, ZoneOption...)} or {@link Dns#getZone(String, ZoneOption...)}.
7373
* The ID is always returned, even if not specified.
7474
*/
7575
enum ZoneField {
@@ -105,7 +105,7 @@ static String selector(ZoneField... fields) {
105105
* The fields of a DNS record.
106106
*
107107
* <p>These values can be used to specify the fields to include in a partial response when calling
108-
* {@code Dns#listDnsRecords(BigInteger, DnsRecordListOption...)} or {@code
108+
* {@link Dns#listDnsRecords(BigInteger, DnsRecordListOption...)} or {@link
109109
* Dns#listDnsRecords(String, DnsRecordListOption...)}. The name is always returned even if not
110110
* selected.
111111
*/
@@ -139,8 +139,8 @@ static String selector(DnsRecordField... fields) {
139139
* The fields of a change request.
140140
*
141141
* <p>These values can be used to specify the fields to include in a partial response when calling
142-
* {@code Dns#applyChangeRequest(ChangeRequest, BigInteger, ChangeRequestOption...)} or {@code
143-
* Dns#applyChangeRequest(ChangeRequest, String, ChangeRequestOption...)} The ID is always
142+
* {@link Dns#applyChangeRequest(BigInteger, ChangeRequest, ChangeRequestOption...)} or {@link
143+
* Dns#applyChangeRequest(String, ChangeRequest, ChangeRequestOption...)} The ID is always
144144
* returned even if not selected.
145145
*/
146146
enum ChangeRequestField {
@@ -313,24 +313,24 @@ public static ZoneListOption pageSize(int pageSize) {
313313
/**
314314
* Class for specifying project options.
315315
*/
316-
class ProjectGetOption extends AbstractOption implements Serializable {
316+
class ProjectOption extends AbstractOption implements Serializable {
317317

318318
private static final long serialVersionUID = 6817937338218847748L;
319319

320-
ProjectGetOption(DnsRpc.Option option, Object value) {
320+
ProjectOption(DnsRpc.Option option, Object value) {
321321
super(option, value);
322322
}
323323

324324
/**
325325
* Returns an option to specify the project's fields to be returned by the RPC call.
326326
*
327327
* <p>If this option is not provided all project fields are returned. {@code
328-
* ProjectGetOption.fields} can be used to specify only the fields of interest. Project ID is
328+
* ProjectOption.fields} can be used to specify only the fields of interest. Project ID is
329329
* always returned, even if not specified. {@link ProjectField} provides a list of fields that
330330
* can be used.
331331
*/
332-
public static ProjectGetOption fields(ProjectField... fields) {
333-
return new ProjectGetOption(DnsRpc.Option.FIELDS, ProjectField.selector(fields));
332+
public static ProjectOption fields(ProjectField... fields) {
333+
return new ProjectOption(DnsRpc.Option.FIELDS, ProjectField.selector(fields));
334334
}
335335
}
336336

@@ -423,19 +423,20 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
423423
/**
424424
* Creates a new zone.
425425
*
426-
* @return ZoneInfo object representing the new zone's metadata. In addition to the name, dns name
427-
* and description (supplied by the user within the {@code zoneInfo} parameter, the returned
428-
* object will include the following read-only fields supplied by the server: creation time, id,
429-
* and list of name servers.
426+
* <p>Returns {@link ZoneInfo} object representing the new zone's information. In addition to the
427+
* name, dns name and description (supplied by the user within the {@code zoneInfo} parameter),
428+
* the returned object will include the following read-only fields supplied by the server:
429+
* creation time, id, and list of name servers.
430+
*
430431
* @throws DnsException upon failure
431432
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/create">Cloud DNS Managed Zones:
432433
* create</a>
433434
*/
434435
ZoneInfo create(ZoneInfo zoneInfo);
435436

436437
/**
437-
* Retrieves the zone by the specified zone name. Returns {@code null} is the zone is not found.
438-
* The returned fields can be optionally restricted by specifying {@code ZoneFieldOptions}.
438+
* Returns the zone by the specified zone name. Returns {@code null} if the zone is not found. The
439+
* returned fields can be optionally restricted by specifying {@link ZoneOption}s.
439440
*
440441
* @throws DnsException upon failure
441442
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/get">Cloud DNS Managed Zones:
@@ -444,8 +445,8 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
444445
ZoneInfo getZone(String zoneName, ZoneOption... options);
445446

446447
/**
447-
* Retrieves the zone by the specified zone name. Returns {@code null} is the zone is not found.
448-
* The returned fields can be optionally restricted by specifying {@code ZoneFieldOptions}.
448+
* Returns the zone by the specified zone id. Returns {@code null} if the zone is not found. The
449+
* returned fields can be optionally restricted by specifying {@link ZoneOption}s.
449450
*
450451
* @throws DnsException upon failure
451452
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/get">Cloud DNS Managed Zones:
@@ -454,35 +455,35 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
454455
ZoneInfo getZone(BigInteger zoneId, ZoneOption... options);
455456

456457
/**
457-
* Lists the zoned inside the project.
458+
* Lists the zones inside the project.
458459
*
459-
* <p>This method returns zone in an unspecified order. New zones do not necessarily appear at the
460-
* end of the list. Use {@link ZoneListOption} to restrict the listing to a domain name, set page
461-
* size, and set page tokens.
460+
* <p>This method returns zones in an unspecified order. New zones do not necessarily appear at
461+
* the end of the list. Use {@link ZoneListOption} to restrict the listing to a domain name, set
462+
* page size, and set page token.
462463
*
463-
* @return {@code Page<Zone>}, a page of zones
464+
* @return a page of zones
464465
* @throws DnsException upon failure
465466
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/list">Cloud DNS Managed Zones:
466467
* list</a>
467468
*/
468469
Page<Zone> listZones(ZoneListOption... options);
469470

470471
/**
471-
* Deletes an existing zone identified by name. Returns true if the zone was successfully deleted
472-
* and false otherwise.
472+
* Deletes an existing zone identified by name. Returns {@code true} if the zone was successfully
473+
* deleted and {@code false} otherwise.
473474
*
474-
* @return {@code true} if zone was found and deleted and false otherwise
475+
* @return {@code true} if zone was found and deleted and {@code false} otherwise
475476
* @throws DnsException upon failure
476477
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/delete">Cloud DNS Managed Zones:
477478
* delete</a>
478479
*/
479480
boolean delete(String zoneName); // delete does not admit any options
480481

481482
/**
482-
* Deletes an existing zone identified by id. Returns true if the zone was successfully deleted
483-
* and false otherwise.
483+
* Deletes an existing zone identified by id. Returns {@code true} if the zone was successfully
484+
* deleted and {@code false} otherwise.
484485
*
485-
* @return {@code true} if zone was found and deleted and false otherwise
486+
* @return {@code true} if zone was found and deleted and {@code false} otherwise
486487
* @throws DnsException upon failure
487488
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/delete">Cloud DNS Managed Zones:
488489
* delete</a>
@@ -492,10 +493,10 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
492493
/**
493494
* Lists the DNS records in the zone identified by name.
494495
*
495-
* <p>The fields to be returned, page size and page tokens can be specified using {@code
496-
* DnsRecordOptions}. Returns null if the zone cannot be found.
496+
* <p>The fields to be returned, page size and page tokens can be specified using {@link
497+
* DnsRecordListOption}s.
497498
*
498-
* @throws DnsException upon failure
499+
* @throws DnsException upon failure or if the zone cannot be found
499500
* @see <a href="https://cloud.google.com/dns/api/v1/resourceRecordSets/list">Cloud DNS
500501
* ResourceRecordSets: list</a>
501502
*/
@@ -504,23 +505,23 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
504505
/**
505506
* Lists the DNS records in the zone identified by ID.
506507
*
507-
* <p>The fields to be returned, page size and page tokens can be specified using {@code
508-
* DnsRecordOptions}. Returns null if the zone cannot be found.
508+
* <p>The fields to be returned, page size and page tokens can be specified using {@link
509+
* DnsRecordListOption}s.
509510
*
510-
* @throws DnsException upon failure
511+
* @throws DnsException upon failure or if the zone cannot be found
511512
* @see <a href="https://cloud.google.com/dns/api/v1/resourceRecordSets/list">Cloud DNS
512513
* ResourceRecordSets: list</a>
513514
*/
514515
Page<DnsRecord> listDnsRecords(BigInteger zoneId, DnsRecordListOption... options);
515516

516517
/**
517-
* Retrieves the metadata about the current project. The returned fields can be optionally
518-
* restricted by specifying {@code ProjectOptions}.
518+
* Retrieves the information about the current project. The returned fields can be optionally
519+
* restricted by specifying {@link ProjectOption}s.
519520
*
520521
* @throws DnsException upon failure
521522
* @see <a href="https://cloud.google.com/dns/api/v1/projects/get">Cloud DNS Projects: get</a>
522523
*/
523-
ProjectInfo getProjectInfo(ProjectGetOption... fields);
524+
ProjectInfo getProjectInfo(ProjectOption... fields);
524525

525526
/**
526527
* Returns the current project id.
@@ -533,77 +534,73 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
533534
BigInteger getProjectNumber();
534535

535536
/**
536-
* Submits a change requests for applying to the zone identified by ID to the service. The
537-
* returned object contains the following read-only fields supplied by the server: id, start time
538-
* and status. time, id, and list of name servers. The returned fields can be modified by {@code
539-
* ChangeRequestFieldOptions}. Returns null if the zone is not found.
537+
* Submits a change request for the specified zone. The returned object contains the following
538+
* read-only fields supplied by the server: id, start time and status. time, id, and list of name
539+
* servers. The fields to be returned can be selected by {@link ChangeRequestOption}s.
540540
*
541-
* @return ChangeRequest object representing the new change request or null if zone is not found
541+
* @return the new {@link ChangeRequest} or {@code null} if zone is not found
542542
* @throws DnsException upon failure
543543
* @see <a href="https://cloud.google.com/dns/api/v1/changes/create">Cloud DNS Changes: create</a>
544544
*/
545-
ChangeRequest applyChangeRequest(ChangeRequest changeRequest, BigInteger zoneId,
546-
ChangeRequestOption... options);
545+
ChangeRequest applyChangeRequest(BigInteger zoneId, ChangeRequest changeRequest,
546+
ChangeRequestOption... options);
547547

548548
/**
549-
* Submits a change requests for applying to the zone identified by name to the service. The
550-
* returned object contains the following read-only fields supplied by the server: id, start time
551-
* and status. time, id, and list of name servers. The returned fields can be modified by {@code
552-
* ChangeRequestFieldOptions}. Returns null if the zone is not found.
549+
* Submits a change request for the specified zone. The returned object contains the following
550+
* read-only fields supplied by the server: id, start time and status. time, id, and list of name
551+
* servers. The fields to be returned can be selected by {@link ChangeRequestOption}s.
553552
*
554-
* @return ChangeRequest object representing the new change request or null if zone is not found
555-
* @throws DnsException upon failure
553+
* @return the new {@link ChangeRequest}
554+
* @throws DnsException upon failure if zone is not found
556555
* @see <a href="https://cloud.google.com/dns/api/v1/changes/create">Cloud DNS Changes: create</a>
557556
*/
558-
ChangeRequest applyChangeRequest(ChangeRequest changeRequest, String zoneName,
559-
ChangeRequestOption... options);
557+
ChangeRequest applyChangeRequest(String zoneName, ChangeRequest changeRequest,
558+
ChangeRequestOption... options);
560559

561560
/**
562561
* Retrieves updated information about a change request previously submitted for a zone identified
563-
* by ID. Returns null if the zone or request cannot be found.
564-
*
565-
* <p>The fields to be returned using {@code ChangeRequestFieldOptions}.
562+
* by ID. Returns {@code null} if the request cannot be found and throws an exception if the zone
563+
* does not exist. The fields to be returned using can be specified using {@link
564+
* ChangeRequestOption}s.
566565
*
567-
* @throws DnsException upon failure
566+
* @throws DnsException upon failure or if the zone cannot be found
568567
* @see <a href="https://cloud.google.com/dns/api/v1/changes/get">Cloud DNS Chages: get</a>
569568
*/
570-
ChangeRequest getChangeRequest(ChangeRequest changeRequest, BigInteger zoneId,
571-
ChangeRequestOption... options);
569+
ChangeRequest getChangeRequest(String changeRequestId, BigInteger zoneId,
570+
ChangeRequestOption... options);
572571

573572
/**
574573
* Retrieves updated information about a change request previously submitted for a zone identified
575-
* by name. Returns null if the zone or request cannot be found.
576-
*
577-
* <p>The fields to be returned using {@code ChangeRequestFieldOptions}.
574+
* by ID. Returns {@code null} if the request cannot be found and throws an exception if the zone
575+
* does not exist. The fields to be returned using can be specified using {@link
576+
* ChangeRequestOption}s.
578577
*
579-
* @throws DnsException upon failure
578+
* @throws DnsException upon failure or if the zone cannot be found
580579
* @see <a href="https://cloud.google.com/dns/api/v1/changes/get">Cloud DNS Chages: get</a>
581580
*/
582-
ChangeRequest getChangeRequest(ChangeRequest changeRequest, String zoneName,
583-
ChangeRequestOption... options);
581+
ChangeRequest getChangeRequest(String changeRequestId, String zoneName,
582+
ChangeRequestOption... options);
584583

585584
/**
586585
* Lists the change requests for the zone identified by ID that were submitted to the service.
587586
*
588-
* <p>The sorting key for changes, fields to be returned, page and page tokens can be specified
589-
* using {@code ChangeRequestListOptions}. Note that the only sorting key currently supported is
590-
* the timestamp of submitting the change request to the service.
587+
* <p>The sorting order for changes (based on when they were received by the server), fields to be
588+
* returned, page size and page token can be specified using {@link ChangeRequestListOption}s.
591589
*
592-
* @return {@code Page<ChangeRequest>}, a page of change requests
593-
* @throws DnsException upon failure
590+
* @return A page of change requests
591+
* @throws DnsException upon failure or if the zone cannot be found
594592
* @see <a href="https://cloud.google.com/dns/api/v1/changes/list">Cloud DNS Chages: list</a>
595593
*/
596594
Page<ChangeRequest> listChangeRequests(BigInteger zoneId, ChangeRequestListOption... options);
597595

598596
/**
599597
* Lists the change requests for the zone identified by name that were submitted to the service.
600598
*
601-
* <p>The sorting key for changes, fields to be returned, page and page tokens can be specified
602-
* using {@code ChangeRequestListOptions}. Note that the only sorting key currently supported is
603-
* the timestamp of submitting the change request to the service.
599+
* <p>The sorting order for changes (based on when they were received by the server), fields to be
600+
* returned, page size and page token can be specified using {@link ChangeRequestListOption}s.
604601
*
605-
* @return {@code Page<ChangeRequest>}, a page of change requests
606-
* @throws DnsException upon failure
602+
* @return A page of change requests
603+
* @throws DnsException upon failure or if the zone cannot be found
607604
* @see <a href="https://cloud.google.com/dns/api/v1/changes/list">Cloud DNS Chages: list</a>
608605
*/
609606
Page<ChangeRequest> listChangeRequests(String zoneName, ChangeRequestListOption... options);

0 commit comments

Comments
 (0)