com.amazonaws.services.codebuild

Class AWSCodeBuildClient

java.lang.Object

com.amazonaws.AmazonWebServiceClient

com.amazonaws.services.codebuild.AWSCodeBuildClient

All Implemented Interfaces:

AWSCodeBuild

Direct Known Subclasses:

AWSCodeBuildAsyncClient

@ThreadSafe
 @Generated(value="com.amazonaws:aws-java-sdk-code-generator")
public class AWSCodeBuildClient
extends AmazonWebServiceClient
implements AWSCodeBuild

Client for accessing AWS CodeBuild. All service calls made using this client are blocking, and will not return until the service call completes.

AWS CodeBuild

AWS CodeBuild is a fully managed build service in the cloud. AWS CodeBuild compiles your source code, runs unit tests, and produces artifacts that are ready to deploy. AWS CodeBuild eliminates the need to provision, manage, and scale your own build servers. It provides prepackaged build environments for the most popular programming languages and build tools, such as Apache Maven, Gradle, and more. You can also fully customize build environments in AWS CodeBuild to use your own build tools. AWS CodeBuild scales automatically to meet peak build requests. You pay only for the build time you consume. For more information about AWS CodeBuild, see the AWS CodeBuild User Guide.

AWS CodeBuild supports these operations:

• BatchDeleteBuilds: Deletes one or more builds.

• BatchGetProjects: Gets information about one or more build projects. A build project defines how AWS CodeBuild runs a build. This includes information such as where to get the source code to build, the build environment to use, the build commands to run, and where to store the build output. A build environment is a representation of operating system, programming language runtime, and tools that AWS CodeBuild uses to run a build. You can add tags to build projects to help manage your resources and costs.

• CreateProject: Creates a build project.

• CreateWebhook: For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, enables AWS CodeBuild to start rebuilding the source code every time a code change is pushed to the repository.

• UpdateWebhook: Changes the settings of an existing webhook.

• DeleteProject: Deletes a build project.

• DeleteWebhook: For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, stops AWS CodeBuild from rebuilding the source code every time a code change is pushed to the repository.

• ListProjects: Gets a list of build project names, with each build project name representing a single build project.

• UpdateProject: Changes the settings of an existing build project.

• BatchGetBuilds: Gets information about one or more builds.

• ListBuilds: Gets a list of build IDs, with each build ID representing a single build.

• ListBuildsForProject: Gets a list of build IDs for the specified build project, with each build ID representing a single build.

• StartBuild: Starts running a build.

• StopBuild: Attempts to stop running a build.

• ListCuratedEnvironmentImages: Gets information about Docker images that are managed by AWS CodeBuild.

• DeleteSourceCredentials: Deletes a set of GitHub, GitHub Enterprise, or Bitbucket source credentials.

• ImportSourceCredentials: Imports the source repository credentials for an AWS CodeBuild project that has its source code stored in a GitHub, GitHub Enterprise, or Bitbucket repository.

• ListSourceCredentials: Returns a list of SourceCredentialsInfo objects. Each SourceCredentialsInfo object includes the authentication type, token ARN, and type of source provider for one set of credentials.

Field Summary

Fields inherited from class com.amazonaws.AmazonWebServiceClient

LOGGING_AWS_REQUEST_METRIC

Fields inherited from interface com.amazonaws.services.codebuild.AWSCodeBuild

ENDPOINT_PREFIX

Constructor Summary

Constructors

Constructor and Description
AWSCodeBuildClient() Deprecated. use AWSCodeBuildClientBuilder.defaultClient()
AWSCodeBuildClient(AWSCredentials awsCredentials) Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) for example: AWSCodeBuildClientBuilder.standard().withCredentials(new AWSStaticCredentialsProvider(awsCredentials)).build();
AWSCodeBuildClient(AWSCredentials awsCredentials, ClientConfiguration clientConfiguration) Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration)
AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider) Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider)
AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration) Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration)
AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration, RequestMetricCollector requestMetricCollector) Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration) and AwsClientBuilder.withMetricsCollector(RequestMetricCollector)
AWSCodeBuildClient(ClientConfiguration clientConfiguration) Deprecated. use AwsClientBuilder.withClientConfiguration(ClientConfiguration)

Method Summary

Modifier and Type	Method and Description
BatchDeleteBuildsResult	batchDeleteBuilds(BatchDeleteBuildsRequest request) Deletes one or more builds.
BatchGetBuildsResult	batchGetBuilds(BatchGetBuildsRequest request) Gets information about builds.
BatchGetProjectsResult	batchGetProjects(BatchGetProjectsRequest request) Gets information about build projects.
static AWSCodeBuildClientBuilder	builder()
CreateProjectResult	createProject(CreateProjectRequest request) Creates a build project.
CreateWebhookResult	createWebhook(CreateWebhookRequest request) For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, enables AWS CodeBuild to start rebuilding the source code every time a code change is pushed to the repository.
DeleteProjectResult	deleteProject(DeleteProjectRequest request) Deletes a build project.
DeleteSourceCredentialsResult	deleteSourceCredentials(DeleteSourceCredentialsRequest request) Deletes a set of GitHub, GitHub Enterprise, or Bitbucket source credentials.
DeleteWebhookResult	deleteWebhook(DeleteWebhookRequest request) For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, stops AWS CodeBuild from rebuilding the source code every time a code change is pushed to the repository.
ResponseMetadata	getCachedResponseMetadata(AmazonWebServiceRequest request) Returns additional metadata for a previously executed successful, request, typically used for debugging issues where a service isn't acting as expected.
ImportSourceCredentialsResult	importSourceCredentials(ImportSourceCredentialsRequest request) Imports the source repository credentials for an AWS CodeBuild project that has its source code stored in a GitHub, GitHub Enterprise, or Bitbucket repository.
InvalidateProjectCacheResult	invalidateProjectCache(InvalidateProjectCacheRequest request) Resets the cache for a project.
ListBuildsResult	listBuilds(ListBuildsRequest request) Gets a list of build IDs, with each build ID representing a single build.
ListBuildsForProjectResult	listBuildsForProject(ListBuildsForProjectRequest request) Gets a list of build IDs for the specified build project, with each build ID representing a single build.
ListCuratedEnvironmentImagesResult	listCuratedEnvironmentImages(ListCuratedEnvironmentImagesRequest request) Gets information about Docker images that are managed by AWS CodeBuild.
ListProjectsResult	listProjects(ListProjectsRequest request) Gets a list of build project names, with each build project name representing a single build project.
ListSourceCredentialsResult	listSourceCredentials(ListSourceCredentialsRequest request) Returns a list of SourceCredentialsInfo objects.
StartBuildResult	startBuild(StartBuildRequest request) Starts running a build.
StopBuildResult	stopBuild(StopBuildRequest request) Attempts to stop running a build.
UpdateProjectResult	updateProject(UpdateProjectRequest request) Changes the settings of a build project.
UpdateWebhookResult	updateWebhook(UpdateWebhookRequest request) Updates the webhook associated with an AWS CodeBuild build project.

Methods inherited from class com.amazonaws.AmazonWebServiceClient

addRequestHandler, addRequestHandler, configureRegion, getClientConfiguration, getEndpointPrefix, getMonitoringListeners, getRequestMetricsCollector, getServiceName, getSignerByURI, getSignerOverride, getSignerRegionOverride, getTimeOffset, makeImmutable, removeRequestHandler, removeRequestHandler, setEndpoint, setEndpoint, setRegion, setServiceNameIntern, setSignerRegionOverride, setTimeOffset, shutdown, withEndpoint, withRegion, withRegion, withTimeOffset

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.amazonaws.services.codebuild.AWSCodeBuild

setEndpoint, setRegion, shutdown

Constructor Detail

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient()

Deprecated. use AWSCodeBuildClientBuilder.defaultClient()

Constructs a new client to invoke service methods on AWS CodeBuild. A credentials provider chain will be used that searches for credentials in this order:

• Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_KEY
• Java System Properties - aws.accessKeyId and aws.secretKey
• Instance profile credentials delivered through the Amazon EC2 metadata service

All service calls made using this new client object are blocking, and will not return until the service call completes.

See Also:

DefaultAWSCredentialsProviderChain

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(ClientConfiguration clientConfiguration)

Deprecated. use AwsClientBuilder.withClientConfiguration(ClientConfiguration)

Constructs a new client to invoke service methods on AWS CodeBuild. A credentials provider chain will be used that searches for credentials in this order:

• Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_KEY
• Java System Properties - aws.accessKeyId and aws.secretKey
• Instance profile credentials delivered through the Amazon EC2 metadata service

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

clientConfiguration - The client configuration options controlling how this client connects to AWS CodeBuild (ex: proxy settings, retry counts, etc.).

See Also:

DefaultAWSCredentialsProviderChain

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(AWSCredentials awsCredentials)

Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) for example: AWSCodeBuildClientBuilder.standard().withCredentials(new AWSStaticCredentialsProvider(awsCredentials)).build();

Constructs a new client to invoke service methods on AWS CodeBuild using the specified AWS account credentials.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

awsCredentials - The AWS credentials (access key ID and secret key) to use when authenticating with AWS services.

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(AWSCredentials awsCredentials,
                                      ClientConfiguration clientConfiguration)

Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration)

Constructs a new client to invoke service methods on AWS CodeBuild using the specified AWS account credentials and client configuration options.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

awsCredentials - The AWS credentials (access key ID and secret key) to use when authenticating with AWS services.

clientConfiguration - The client configuration options controlling how this client connects to AWS CodeBuild (ex: proxy settings, retry counts, etc.).

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider)

Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider)

Constructs a new client to invoke service methods on AWS CodeBuild using the specified AWS account credentials provider.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

awsCredentialsProvider - The AWS credentials provider which will provide credentials to authenticate requests with AWS services.

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider,
                                      ClientConfiguration clientConfiguration)

Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration)

Constructs a new client to invoke service methods on AWS CodeBuild using the specified AWS account credentials provider and client configuration options.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

awsCredentialsProvider - The AWS credentials provider which will provide credentials to authenticate requests with AWS services.

clientConfiguration - The client configuration options controlling how this client connects to AWS CodeBuild (ex: proxy settings, retry counts, etc.).

AWSCodeBuildClient

@Deprecated
public AWSCodeBuildClient(AWSCredentialsProvider awsCredentialsProvider,
                                      ClientConfiguration clientConfiguration,
                                      RequestMetricCollector requestMetricCollector)

Deprecated. use AwsClientBuilder.withCredentials(AWSCredentialsProvider) and AwsClientBuilder.withClientConfiguration(ClientConfiguration) and AwsClientBuilder.withMetricsCollector(RequestMetricCollector)

Constructs a new client to invoke service methods on AWS CodeBuild using the specified AWS account credentials provider, client configuration options, and request metric collector.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:

awsCredentialsProvider - The AWS credentials provider which will provide credentials to authenticate requests with AWS services.

clientConfiguration - The client configuration options controlling how this client connects to AWS CodeBuild (ex: proxy settings, retry counts, etc.).

requestMetricCollector - optional request metric collector

Method Detail

builder

public static AWSCodeBuildClientBuilder builder()

batchDeleteBuilds

public BatchDeleteBuildsResult batchDeleteBuilds(BatchDeleteBuildsRequest request)

Deletes one or more builds.

Specified by:

batchDeleteBuilds in interface AWSCodeBuild

Parameters:

batchDeleteBuildsRequest -

Returns:

Result of the BatchDeleteBuilds operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

batchGetBuilds

public BatchGetBuildsResult batchGetBuilds(BatchGetBuildsRequest request)

Gets information about builds.

Specified by:

batchGetBuilds in interface AWSCodeBuild

Parameters:

batchGetBuildsRequest -

Returns:

Result of the BatchGetBuilds operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

Samples:

• To get information about builds

  The following example gets information about builds with the specified build IDs.
  

  AWSCodeBuild client = AWSCodeBuildClientBuilder.standard().build();
  BatchGetBuildsRequest request = new BatchGetBuildsRequest().withIds("codebuild-demo-project:9b0ac37f-d19e-4254-9079-f47e9a389eEX",
          "codebuild-demo-project:b79a46f7-1473-4636-a23f-da9c45c208EX");
  BatchGetBuildsResult response = client.batchGetBuilds(request);

batchGetProjects

public BatchGetProjectsResult batchGetProjects(BatchGetProjectsRequest request)

Gets information about build projects.

Specified by:

batchGetProjects in interface AWSCodeBuild

Parameters:

batchGetProjectsRequest -

Returns:

Result of the BatchGetProjects operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

createProject

public CreateProjectResult createProject(CreateProjectRequest request)

Creates a build project.

Specified by:

createProject in interface AWSCodeBuild

Parameters:

createProjectRequest -

Returns:

Result of the CreateProject operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceAlreadyExistsException - The specified AWS resource cannot be created, because an AWS resource with the same settings already exists.

AccountLimitExceededException - An AWS service limit was exceeded for the calling AWS account.

See Also:

AWS API Documentation

createWebhook

public CreateWebhookResult createWebhook(CreateWebhookRequest request)

For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, enables AWS CodeBuild to start rebuilding the source code every time a code change is pushed to the repository.

If you enable webhooks for an AWS CodeBuild project, and the project is used as a build step in AWS CodePipeline, then two identical builds are created for each commit. One build is triggered through webhooks, and one through AWS CodePipeline. Because billing is on a per-build basis, you are billed for both builds. Therefore, if you are using AWS CodePipeline, we recommend that you disable webhooks in AWS CodeBuild. In the AWS CodeBuild console, clear the Webhook box. For more information, see step 5 in Change a Build Project's Settings.

Specified by:

createWebhook in interface AWSCodeBuild

Parameters:

createWebhookRequest -

Returns:

Result of the CreateWebhook operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

OAuthProviderException - There was a problem with the underlying OAuth provider.

ResourceAlreadyExistsException - The specified AWS resource cannot be created, because an AWS resource with the same settings already exists.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

deleteProject

public DeleteProjectResult deleteProject(DeleteProjectRequest request)

Deletes a build project.

Specified by:

deleteProject in interface AWSCodeBuild

Parameters:

deleteProjectRequest -

Returns:

Result of the DeleteProject operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

deleteSourceCredentials

public DeleteSourceCredentialsResult deleteSourceCredentials(DeleteSourceCredentialsRequest request)

Deletes a set of GitHub, GitHub Enterprise, or Bitbucket source credentials.

Specified by:

deleteSourceCredentials in interface AWSCodeBuild

Parameters:

deleteSourceCredentialsRequest -

Returns:

Result of the DeleteSourceCredentials operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

deleteWebhook

public DeleteWebhookResult deleteWebhook(DeleteWebhookRequest request)

For an existing AWS CodeBuild build project that has its source code stored in a GitHub or Bitbucket repository, stops AWS CodeBuild from rebuilding the source code every time a code change is pushed to the repository.

Specified by:

deleteWebhook in interface AWSCodeBuild

Parameters:

deleteWebhookRequest -

Returns:

Result of the DeleteWebhook operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

OAuthProviderException - There was a problem with the underlying OAuth provider.

See Also:

AWS API Documentation

importSourceCredentials

public ImportSourceCredentialsResult importSourceCredentials(ImportSourceCredentialsRequest request)

Imports the source repository credentials for an AWS CodeBuild project that has its source code stored in a GitHub, GitHub Enterprise, or Bitbucket repository.

Specified by:

importSourceCredentials in interface AWSCodeBuild

Parameters:

importSourceCredentialsRequest -

Returns:

Result of the ImportSourceCredentials operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

AccountLimitExceededException - An AWS service limit was exceeded for the calling AWS account.

ResourceAlreadyExistsException - The specified AWS resource cannot be created, because an AWS resource with the same settings already exists.

See Also:

AWS API Documentation

invalidateProjectCache

public InvalidateProjectCacheResult invalidateProjectCache(InvalidateProjectCacheRequest request)

Resets the cache for a project.

Specified by:

invalidateProjectCache in interface AWSCodeBuild

Parameters:

invalidateProjectCacheRequest -

Returns:

Result of the InvalidateProjectCache operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

listBuilds

public ListBuildsResult listBuilds(ListBuildsRequest request)

Gets a list of build IDs, with each build ID representing a single build.

Specified by:

listBuilds in interface AWSCodeBuild

Parameters:

listBuildsRequest -

Returns:

Result of the ListBuilds operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

listBuildsForProject

public ListBuildsForProjectResult listBuildsForProject(ListBuildsForProjectRequest request)

Gets a list of build IDs for the specified build project, with each build ID representing a single build.

Specified by:

listBuildsForProject in interface AWSCodeBuild

Parameters:

listBuildsForProjectRequest -

Returns:

Result of the ListBuildsForProject operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

listCuratedEnvironmentImages

public ListCuratedEnvironmentImagesResult listCuratedEnvironmentImages(ListCuratedEnvironmentImagesRequest request)

Gets information about Docker images that are managed by AWS CodeBuild.

Specified by:

listCuratedEnvironmentImages in interface AWSCodeBuild

Parameters:

listCuratedEnvironmentImagesRequest -

Returns:

Result of the ListCuratedEnvironmentImages operation returned by the service.

See Also:

AWS API Documentation

listProjects

public ListProjectsResult listProjects(ListProjectsRequest request)

Gets a list of build project names, with each build project name representing a single build project.

Specified by:

listProjects in interface AWSCodeBuild

Parameters:

listProjectsRequest -

Returns:

Result of the ListProjects operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

See Also:

AWS API Documentation

listSourceCredentials

public ListSourceCredentialsResult listSourceCredentials(ListSourceCredentialsRequest request)

Returns a list of SourceCredentialsInfo objects.

Specified by:

listSourceCredentials in interface AWSCodeBuild

Parameters:

listSourceCredentialsRequest -

Returns:

Result of the ListSourceCredentials operation returned by the service.

See Also:

AWS API Documentation

startBuild

public StartBuildResult startBuild(StartBuildRequest request)

Starts running a build.

Specified by:

startBuild in interface AWSCodeBuild

Parameters:

startBuildRequest -

Returns:

Result of the StartBuild operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

AccountLimitExceededException - An AWS service limit was exceeded for the calling AWS account.

See Also:

AWS API Documentation

stopBuild

public StopBuildResult stopBuild(StopBuildRequest request)

Attempts to stop running a build.

Specified by:

stopBuild in interface AWSCodeBuild

Parameters:

stopBuildRequest -

Returns:

Result of the StopBuild operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

updateProject

public UpdateProjectResult updateProject(UpdateProjectRequest request)

Changes the settings of a build project.

Specified by:

updateProject in interface AWSCodeBuild

Parameters:

updateProjectRequest -

Returns:

Result of the UpdateProject operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

See Also:

AWS API Documentation

updateWebhook

public UpdateWebhookResult updateWebhook(UpdateWebhookRequest request)

Updates the webhook associated with an AWS CodeBuild build project.

If you use Bitbucket for your repository, rotateSecret is ignored.

Specified by:

updateWebhook in interface AWSCodeBuild

Parameters:

updateWebhookRequest -

Returns:

Result of the UpdateWebhook operation returned by the service.

Throws:

InvalidInputException - The input value that was provided is not valid.

ResourceNotFoundException - The specified AWS resource cannot be found.

OAuthProviderException - There was a problem with the underlying OAuth provider.

See Also:

AWS API Documentation

getCachedResponseMetadata

public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)

Returns additional metadata for a previously executed successful, request, typically used for debugging issues where a service isn't acting as expected. This data isn't considered part of the result data returned by an operation, so it's available through this separate, diagnostic interface.

Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic information for an executed request, you should use this method to retrieve it as soon as possible after executing the request.

Specified by:

getCachedResponseMetadata in interface AWSCodeBuild

Parameters:

request - The originally executed request

Returns:

The response metadata for the specified request, or null if none is available.