Skip to content

Commit

Permalink
Fixed documentation and some code formatting. Declared exceptions to be
Browse files Browse the repository at this point in the history 
thrown when parent objects do not exist. Changed contracts of
applyChangeRequest and getChangeRequest methods. Adjusted tests.
  • Loading branch information
@mderka
mderka committed Feb 2, 2016
1 parent a69101a commit e083dfd
Show file tree
Hide file tree
Showing 4 changed files with 171 additions and 182 deletions.
147 changes: 72 additions & 75 deletions gcloud-java-dns/src/main/java/com/google/gcloud/dns/Dns.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ public interface Dns extends Service<DnsOptions> {
* The fields of a project.
*
* <p>These values can be used to specify the fields to include in a partial response when calling
* {@code Dns#getProjectInfo(ProjectGetOption...)}. Project ID is always returned, even if not
* {@link Dns#getProjectInfo(ProjectOption...)}. Project ID is always returned, even if not
* specified.
*/
enum ProjectField {
Expand Down Expand Up @@ -69,7 +69,7 @@ static String selector(ProjectField... fields) {
* The fields of a zone.
*
* <p>These values can be used to specify the fields to include in a partial response when calling
* {@code Dns#getZone(BigInteger, ZoneOption...)} or {@code Dns#getZone(String, ZoneOption...)}.
* {@link Dns#getZone(BigInteger, ZoneOption...)} or {@link Dns#getZone(String, ZoneOption...)}.
* The ID is always returned, even if not specified.
*/
enum ZoneField {
Expand Down Expand Up @@ -105,7 +105,7 @@ static String selector(ZoneField... fields) {
* The fields of a DNS record.
*
* <p>These values can be used to specify the fields to include in a partial response when calling
* {@code Dns#listDnsRecords(BigInteger, DnsRecordListOption...)} or {@code
* {@link Dns#listDnsRecords(BigInteger, DnsRecordListOption...)} or {@link
* Dns#listDnsRecords(String, DnsRecordListOption...)}. The name is always returned even if not
* selected.
*/
Expand Down Expand Up @@ -139,8 +139,8 @@ static String selector(DnsRecordField... fields) {
* The fields of a change request.
*
* <p>These values can be used to specify the fields to include in a partial response when calling
* {@code Dns#applyChangeRequest(ChangeRequest, BigInteger, ChangeRequestOption...)} or {@code
* Dns#applyChangeRequest(ChangeRequest, String, ChangeRequestOption...)} The ID is always
* {@link Dns#applyChangeRequest(BigInteger, ChangeRequest, ChangeRequestOption...)} or {@link
* Dns#applyChangeRequest(String, ChangeRequest, ChangeRequestOption...)} The ID is always
* returned even if not selected.
*/
enum ChangeRequestField {
Expand Down Expand Up @@ -313,24 +313,24 @@ public static ZoneListOption pageSize(int pageSize) {
/**
* Class for specifying project options.
*/
class ProjectGetOption extends AbstractOption implements Serializable {
class ProjectOption extends AbstractOption implements Serializable {

private static final long serialVersionUID = 6817937338218847748L;

ProjectGetOption(DnsRpc.Option option, Object value) {
ProjectOption(DnsRpc.Option option, Object value) {
super(option, value);
}

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

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

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

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

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

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

/**
* Deletes an existing zone identified by id. Returns true if the zone was successfully deleted
* and false otherwise.
* Deletes an existing zone identified by id. Returns {@code true} if the zone was successfully
* deleted and {@code false} otherwise.
*
* @return {@code true} if zone was found and deleted and false otherwise
* @return {@code true} if zone was found and deleted and {@code false} otherwise
* @throws DnsException upon failure
* @see <a href="https://cloud.google.com/dns/api/v1/managedZones/delete">Cloud DNS Managed Zones:
* delete</a>
Expand All @@ -492,10 +493,10 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
/**
* Lists the DNS records in the zone identified by name.
*
* <p>The fields to be returned, page size and page tokens can be specified using {@code
* DnsRecordOptions}. Returns null if the zone cannot be found.
* <p>The fields to be returned, page size and page tokens can be specified using {@link
* DnsRecordListOption}s.
*
* @throws DnsException upon failure
* @throws DnsException upon failure or if the zone cannot be found
* @see <a href="https://cloud.google.com/dns/api/v1/resourceRecordSets/list">Cloud DNS
* ResourceRecordSets: list</a>
*/
Expand All @@ -504,23 +505,23 @@ public static ChangeRequestListOption sortOrder(SortingOrder order) {
/**
* Lists the DNS records in the zone identified by ID.
*
* <p>The fields to be returned, page size and page tokens can be specified using {@code
* DnsRecordOptions}. Returns null if the zone cannot be found.
* <p>The fields to be returned, page size and page tokens can be specified using {@link
* DnsRecordListOption}s.
*
* @throws DnsException upon failure
* @throws DnsException upon failure or if the zone cannot be found
* @see <a href="https://cloud.google.com/dns/api/v1/resourceRecordSets/list">Cloud DNS
* ResourceRecordSets: list</a>
*/
Page<DnsRecord> listDnsRecords(BigInteger zoneId, DnsRecordListOption... options);

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

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

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

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

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

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

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

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

0 comments on commit e083dfd

Please sign in to comment.