Skip to content

Commit

Permalink
fix: fixed javadoc errors (#945)
Browse files Browse the repository at this point in the history 
* fix: fixed javadoc errors

Update javadoc source version to 8 and modified configuration to ignore 'missing' javadoc comments since missing unnecessary @returns are getting flagged as an error.

* Add missing @params and @return

* linting fix

* revert pom.xml changes

* Addressing PR comments

Co-authored-by: Leo <39062083+lsirac@users.noreply.github.com>
  • Loading branch information
@aeitzman @lsirac
aeitzman and lsirac committed Oct 14, 2022
1 parent abde3e5 commit 1ddc994
Show file tree
Hide file tree
Showing 3 changed files with 127 additions and 19 deletions.
32 changes: 30 additions & 2 deletions oauth2_http/java/com/google/auth/oauth2/CredentialAccessBoundary.java
View file
Expand Up @@ -120,6 +120,9 @@ private Builder() {}
* Sets the list of {@link AccessBoundaryRule}'s.
*
* <p>This list must not exceed 10 rules.
*
* @param rule the collection of rules to be set, should not be null
* @return this {@code Builder} object
*/
public Builder setRules(List<AccessBoundaryRule> rule) {
accessBoundaryRules = new ArrayList<>(checkNotNull(rule));
Expand Down Expand Up @@ -211,6 +214,9 @@ private Builder() {}
* access to.
*
* <p>For example: "//storage.googleapis.com/projects/_/buckets/example".
*
* @param availableResource the resource name to set
* @return this {@code Builder} object
*/
public Builder setAvailableResource(String availableResource) {
this.availableResource = availableResource;
Expand All @@ -222,6 +228,9 @@ public Builder setAvailableResource(String availableResource) {
* roles prefixed by inRole.
*
* <p>For example: {"inRole:roles/storage.objectViewer"}.
*
* @param availablePermissions the collection of permissions to set, should not be null
* @return this {@code Builder} object
*/
public Builder setAvailablePermissions(List<String> availablePermissions) {
this.availablePermissions = new ArrayList<>(checkNotNull(availablePermissions));
Expand All @@ -233,6 +242,9 @@ public Builder setAvailablePermissions(List<String> availablePermissions) {
* inRole.
*
* <p>For example: "inRole:roles/storage.objectViewer".
*
* @param availablePermission a permission to add, should not be null
* @return this {@code Builder} object
*/
public Builder addAvailablePermission(String availablePermission) {
if (availablePermissions == null) {
Expand All @@ -245,6 +257,9 @@ public Builder addAvailablePermission(String availablePermission) {
/**
* Sets the availability condition which is an IAM condition that defines constraints to apply
* to the token expressed in CEL format.
*
* @param availabilityCondition the {@code AvailabilityCondition} to set
* @return this {@code Builder} object
*/
public Builder setAvailabilityCondition(AvailabilityCondition availabilityCondition) {
this.availabilityCondition = availabilityCondition;
Expand Down Expand Up @@ -318,19 +333,32 @@ private Builder() {}
* <p>This expression specifies the Cloud Storage object where permissions are available.
* See <a href='https://cloud.google.com/iam/docs/conditions-overview#cel'>for more
* information.</a>
*
* @param expression the expression to set
* @return this {@code Builder} object
*/
public Builder setExpression(String expression) {
this.expression = expression;
return this;
}

/** Sets the optional title that identifies the purpose of the condition. */
/**
* Sets the optional title that identifies the purpose of the condition.
*
* @param title the title to set
* @return this {@code Builder} object
*/
public Builder setTitle(String title) {
this.title = title;
return this;
}

/** Sets the description that details the purpose of the condition. */
/**
* Sets the description that details the purpose of the condition.
*
* @param description the description to set
* @return this {@code Builder} object
*/
public Builder setDescription(String description) {
this.description = description;
return this;
Expand Down
106 changes: 93 additions & 13 deletions oauth2_http/java/com/google/auth/oauth2/ExternalAccountCredentials.java
View file
Expand Up @@ -159,9 +159,25 @@ protected ExternalAccountCredentials(
}

/**
* See {@link ExternalAccountCredentials#ExternalAccountCredentials(HttpTransportFactory, String,
* String, String, CredentialSource, String, String, String, String, String, Collection)}
* Constructor with minimum identifying information and custom HTTP transport. Does not support
* workforce credentials.
*
* @param transportFactory HTTP transport factory, creates the transport used to get access tokens
* @param audience the Security Token Service audience, which is usually the fully specified
* resource name of the workload/workforce pool provider
* @param subjectTokenType the Security Token Service subject token type based on the OAuth 2.0
* token exchange spec. Indicates the type of the security token in the credential file
* @param tokenUrl the Security Token Service token exchange endpoint
* @param tokenInfoUrl the endpoint used to retrieve account related information. Required for
* gCloud session account identification.
* @param credentialSource the external credential source
* @param serviceAccountImpersonationUrl the URL for the service account impersonation request.
* This URL is required for some APIs. If this URL is not available, the access token from the
* Security Token Service is used directly. May be null.
* @param quotaProjectId the project used for quota and billing purposes. May be null.
* @param clientId client ID of the service account from the console. May be null.
* @param clientSecret client secret of the service account from the console. May be null.
* @param scopes the scopes to request during the authorization grant. May be null.
* @param environmentProvider the environment provider. May be null. Defaults to {@link
* SystemEnvironmentProvider}.
*/
Expand Down Expand Up @@ -211,6 +227,8 @@ protected ExternalAccountCredentials(
/**
* Internal constructor with minimum identifying information and custom HTTP transport. See {@link
* ExternalAccountCredentials.Builder}.
*
* @param builder the {@code Builder} object used to construct the credentials.
*/
protected ExternalAccountCredentials(ExternalAccountCredentials.Builder builder) {
this.transportFactory =
Expand Down Expand Up @@ -494,6 +512,7 @@ protected AccessToken exchangeExternalCredentialForAccessToken(
* source.
*
* @return the external subject token
* @throws IOException if the subject token cannot be retrieved
*/
public abstract String retrieveSubjectToken() throws IOException;

Expand Down Expand Up @@ -522,7 +541,7 @@ public String getServiceAccountImpersonationUrl() {
return serviceAccountImpersonationUrl;
}

/** The service account email to be impersonated, if available. */
/** @return The service account email to be impersonated, if available */
@Nullable
public String getServiceAccountEmail() {
if (serviceAccountImpersonationUrl == null || serviceAccountImpersonationUrl.isEmpty()) {
Expand Down Expand Up @@ -567,8 +586,8 @@ EnvironmentProvider getEnvironmentProvider() {
}

/**
* Returns whether the current configuration is for Workforce Pools (which enable 3p user
* identities, rather than workloads).
* @return whether the current configuration is for Workforce Pools (which enable 3p user
* identities, rather than workloads)
*/
public boolean isWorkforcePoolConfiguration() {
Pattern workforceAudiencePattern =
Expand Down Expand Up @@ -728,7 +747,12 @@ protected Builder(ExternalAccountCredentials credentials) {
this.serviceAccountImpersonationOptions = credentials.serviceAccountImpersonationOptions;
}

/** Sets the HTTP transport factory, creates the transport used to get access tokens. */
/**
* Sets the HTTP transport factory, creates the transport used to get access tokens.
*
* @param transportFactory the {@code HttpTransportFactory} to set
* @return this {@code Builder} object
*/
public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) {
this.transportFactory = transportFactory;
return this;
Expand All @@ -737,6 +761,9 @@ public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) {
/**
* Sets the Security Token Service audience, which is usually the fully specified resource name
* of the workload/workforce pool provider.
*
* @param audience the Security Token Service audience to set
* @return this {@code Builder} object
*/
public Builder setAudience(String audience) {
this.audience = audience;
Expand All @@ -746,19 +773,32 @@ public Builder setAudience(String audience) {
/**
* Sets the Security Token Service subject token type based on the OAuth 2.0 token exchange
* spec. Indicates the type of the security token in the credential file.
*
* @param subjectTokenType the Security Token Service subject token type to set
* @return this {@code Builder} object
*/
public Builder setSubjectTokenType(String subjectTokenType) {
this.subjectTokenType = subjectTokenType;
return this;
}

/** Sets the Security Token Service token exchange endpoint. */
/**
* Sets the Security Token Service token exchange endpoint.
*
* @param tokenUrl the Security Token Service token exchange url to set
* @return this {@code Builder} object
*/
public Builder setTokenUrl(String tokenUrl) {
this.tokenUrl = tokenUrl;
return this;
}

/** Sets the external credential source. */
/**
* Sets the external credential source.
*
* @param credentialSource the {@code CredentialSource} to set
* @return this {@code Builder} object
*/
public Builder setCredentialSource(CredentialSource credentialSource) {
this.credentialSource = credentialSource;
return this;
Expand All @@ -768,6 +808,9 @@ public Builder setCredentialSource(CredentialSource credentialSource) {
* Sets the optional URL used for service account impersonation, which is required for some
* APIs. If this URL is not available, the access token from the Security Token Service is used
* directly.
*
* @param serviceAccountImpersonationUrl the service account impersonation url to set
* @return this {@code Builder} object
*/
public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonationUrl) {
this.serviceAccountImpersonationUrl = serviceAccountImpersonationUrl;
Expand All @@ -777,31 +820,54 @@ public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonat
/**
* Sets the optional endpoint used to retrieve account related information. Required for gCloud
* session account identification.
*
* @param tokenInfoUrl the token info url to set
* @return this {@code Builder} object
*/
public Builder setTokenInfoUrl(String tokenInfoUrl) {
this.tokenInfoUrl = tokenInfoUrl;
return this;
}

/** Sets the optional project used for quota and billing purposes. */
/**
* Sets the optional project used for quota and billing purposes.
*
* @param quotaProjectId the quota and billing project id to set
* @return this {@code Builder} object
*/
public Builder setQuotaProjectId(String quotaProjectId) {
this.quotaProjectId = quotaProjectId;
return this;
}

/** Sets the optional client ID of the service account from the console. */
/**
* Sets the optional client ID of the service account from the console.
*
* @param clientId the service account client id to set
* @return this {@code Builder} object
*/
public Builder setClientId(String clientId) {
this.clientId = clientId;
return this;
}

/** Sets the optional client secret of the service account from the console. */
/**
* Sets the optional client secret of the service account from the console.
*
* @param clientSecret the service account client secret to set
* @return this {@code Builder} object
*/
public Builder setClientSecret(String clientSecret) {
this.clientSecret = clientSecret;
return this;
}

/** Sets the optional scopes to request during the authorization grant. */
/**
* Sets the optional scopes to request during the authorization grant.
*
* @param scopes the request scopes to set
* @return this {@code Builder} object
*/
public Builder setScopes(Collection<String> scopes) {
this.scopes = scopes;
return this;
Expand All @@ -811,18 +877,32 @@ public Builder setScopes(Collection<String> scopes) {
* Sets the optional workforce pool user project number when the credential corresponds to a
* workforce pool and not a workload identity pool. The underlying principal must still have
* serviceusage.services.use IAM permission to use the project for billing/quota.
*
* @param workforcePoolUserProject the workforce pool user project number to set
* @return this {@code Builder} object
*/
public Builder setWorkforcePoolUserProject(String workforcePoolUserProject) {
this.workforcePoolUserProject = workforcePoolUserProject;
return this;
}

/** Sets the optional service account impersonation options. */
/**
* Sets the optional service account impersonation options.
*
* @param optionsMap the service account impersonation options to set
* @return this {@code Builder} object
*/
public Builder setServiceAccountImpersonationOptions(Map<String, Object> optionsMap) {
this.serviceAccountImpersonationOptions = new ServiceAccountImpersonationOptions(optionsMap);
return this;
}

/**
* Sets the optional Environment Provider.
*
* @param environmentProvider the {@code EnvironmentProvider} to set
* @return this {@code Builder} object
*/
Builder setEnvironmentProvider(EnvironmentProvider environmentProvider) {
this.environmentProvider = environmentProvider;
return this;
Expand Down
8 changes: 4 additions & 4 deletions oauth2_http/java/com/google/auth/oauth2/PluggableAuthCredentials.java
View file
Expand Up @@ -84,17 +84,17 @@
* "code": "401",
* "message": "Error message."
* }
* </pre>
*
* <p> The `expiration_time` field in the JSON response is only required for successful
* responses when an output file was specified in the credential configuration.
* <p>The `expiration_time` field in the JSON response is only required for successful responses
* when an output file was specified in the credential configuration.
*
* The auth libraries will populate certain environment variables that will be accessible by the
* <p>The auth libraries will populate certain environment variables that will be accessible by the
* executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE,
* GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and
* GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE.
*
* <p>Please see this repositories README for a complete executable request/response specification.
* </pre>
*/
public class PluggableAuthCredentials extends ExternalAccountCredentials {

Expand Down

0 comments on commit 1ddc994

Please sign in to comment.