Package software.amazon.awscdk.services.s3

Interface IBucket.Jsii$Default

All Superinterfaces:
IBucket, IConstruct, software.constructs.IConstruct, IConstruct.Jsii$Default, software.constructs.IConstruct.Jsii$Default, IDependable, IDependable.Jsii$Default, IResource, IResource.Jsii$Default, software.amazon.jsii.JsiiSerializable
All Known Implementing Classes:
IBucket.Jsii$Proxy
Enclosing interface:
IBucket
@Internal public static interface IBucket.Jsii$Default extends IBucket, IResource.Jsii$Default
Internal default implementation for IBucket.

  • Method Details

    • getNode

      @Stability(Stable) @NotNull default ConstructNode getNode()
      The construct tree node for this construct.
      Specified by:
      getNode in interface IConstruct
      Specified by:
      getNode in interface IConstruct.Jsii$Default
      Specified by:
      getNode in interface IResource.Jsii$Default

    • getEnv

      @Stability(Stable) @NotNull default ResourceEnvironment getEnv()
      The environment this resource belongs to.

      For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

      Specified by:
      getEnv in interface IResource
      Specified by:
      getEnv in interface IResource.Jsii$Default

    • getStack

      @Stability(Stable) @NotNull default Stack getStack()
      The stack in which this resource is defined.
      Specified by:
      getStack in interface IResource
      Specified by:
      getStack in interface IResource.Jsii$Default

    • getBucketArn

      @Stability(Stable) @NotNull default String getBucketArn()
      The ARN of the bucket.
      Specified by:
      getBucketArn in interface IBucket

    • getBucketDomainName

      @Stability(Stable) @NotNull default String getBucketDomainName()
      The IPv4 DNS name of the specified bucket.
      Specified by:
      getBucketDomainName in interface IBucket

    • getBucketDualStackDomainName

      @Stability(Stable) @NotNull default String getBucketDualStackDomainName()
      The IPv6 DNS name of the specified bucket.
      Specified by:
      getBucketDualStackDomainName in interface IBucket

    • getBucketName

      @Stability(Stable) @NotNull default String getBucketName()
      The name of the bucket.
      Specified by:
      getBucketName in interface IBucket

    • getBucketRegionalDomainName

      @Stability(Stable) @NotNull default String getBucketRegionalDomainName()
      The regional domain name of the specified bucket.
      Specified by:
      getBucketRegionalDomainName in interface IBucket

    • getBucketWebsiteDomainName

      @Stability(Stable) @NotNull default String getBucketWebsiteDomainName()
      The Domain name of the static website.
      Specified by:
      getBucketWebsiteDomainName in interface IBucket

    • getBucketWebsiteUrl

      @Stability(Stable) @NotNull default String getBucketWebsiteUrl()
      The URL of the static website.
      Specified by:
      getBucketWebsiteUrl in interface IBucket

    • getEncryptionKey

      @Stability(Stable) @Nullable default IKey getEncryptionKey()
      Optional KMS encryption key associated with this bucket.
      Specified by:
      getEncryptionKey in interface IBucket

    • getIsWebsite

      @Stability(Stable) @Nullable default Boolean getIsWebsite()
      If this bucket has been configured for static website hosting.
      Specified by:
      getIsWebsite in interface IBucket

    • getPolicy

      @Stability(Stable) @Nullable default BucketPolicy getPolicy()
      The resource policy associated with this bucket.

      If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

      Specified by:
      getPolicy in interface IBucket

    • setPolicy

      @Stability(Stable) default void setPolicy(@Nullable BucketPolicy value)
      The resource policy associated with this bucket.

      If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

      Specified by:
      setPolicy in interface IBucket

    • applyRemovalPolicy

      @Stability(Stable) default void applyRemovalPolicy(@NotNull RemovalPolicy policy)
      Apply the given removal policy to this resource.

      The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

      The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

      Specified by:
      applyRemovalPolicy in interface IResource
      Specified by:
      applyRemovalPolicy in interface IResource.Jsii$Default
      Parameters:
      policy - This parameter is required.

    • addEventNotification

      @Stability(Stable) default void addEventNotification(@NotNull EventType event, @NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Adds a bucket notification event destination.

      Example: 

       Function myLambda;
 Bucket bucket = new Bucket(this, "MyBucket");
 bucket.addEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(myLambda), NotificationKeyFilter.builder().prefix("home/myusername/*").build());

      Specified by:
      addEventNotification in interface IBucket
      Parameters:
      event - The event to trigger the notification. This parameter is required.
      dest - The notification destination (Lambda, SNS Topic or SQS Queue). This parameter is required.
      filters - S3 object key filter rules to determine which objects trigger this event. This parameter is required.
      See Also:

    • addObjectCreatedNotification

      @Stability(Stable) default void addObjectCreatedNotification(@NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Subscribes a destination to receive notifications when an object is created in the bucket.

      This is identical to calling onEvent(s3.EventType.OBJECT_CREATED).

      Specified by:
      addObjectCreatedNotification in interface IBucket
      Parameters:
      dest - The notification destination (see onEvent). This parameter is required.
      filters - Filters (see onEvent). This parameter is required.

    • addObjectRemovedNotification

      @Stability(Stable) default void addObjectRemovedNotification(@NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Subscribes a destination to receive notifications when an object is removed from the bucket.

      This is identical to calling onEvent(EventType.OBJECT_REMOVED).

      Specified by:
      addObjectRemovedNotification in interface IBucket
      Parameters:
      dest - The notification destination (see onEvent). This parameter is required.
      filters - Filters (see onEvent). This parameter is required.

    • addToResourcePolicy

      @Stability(Stable) @NotNull default AddToResourcePolicyResult addToResourcePolicy(@NotNull PolicyStatement permission)
      Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use bucketArn and arnForObjects(keys) to obtain ARNs for this bucket or objects.

      Note that the policy statement may or may not be added to the policy. For example, when an IBucket is created from an existing bucket, it's not possible to tell whether the bucket already has a policy attached, let alone to re-use that policy to add more statements to it. So it's safest to do nothing in these cases.

      Specified by:
      addToResourcePolicy in interface IBucket
      Parameters:
      permission - the policy statement to be added to the bucket's policy. This parameter is required.
      Returns:
      metadata about the execution of this method. If the policy was not added, the value of statementAdded will be false. You should always check this value to make sure that the operation was actually carried out. Otherwise, synthesis and deploy will terminate silently, which may be confusing.

    • arnForObjects

      @Stability(Stable) @NotNull default String arnForObjects(@NotNull String keyPattern)
      Returns an ARN that represents all objects within the bucket that match the key pattern specified.

      To represent all keys, specify "*".

      Specified by:
      arnForObjects in interface IBucket
      Parameters:
      keyPattern - This parameter is required.

    • grantDelete

      @Stability(Stable) @NotNull default Grant grantDelete(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

      Specified by:
      grantDelete in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantPublicAccess

      @Stability(Stable) @NotNull default Grant grantPublicAccess(@Nullable String keyPrefix, @NotNull @NotNull String... allowedActions)
      Allows unrestricted access to objects from this bucket.

      IMPORTANT: This permission allows anyone to perform actions on S3 objects in this bucket, which is useful for when you configure your bucket as a website and want everyone to be able to read objects in the bucket without needing to authenticate.

      Without arguments, this method will grant read ("s3:GetObject") access to all objects ("*") in the bucket.

      The method returns the iam.Grant object, which can then be modified as needed. For example, you can add a condition that will restrict access only to an IPv4 range like this: 

        const grant = bucket.grantPublicAccess();
  grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” });

      Specified by:
      grantPublicAccess in interface IBucket
      Parameters:
      keyPrefix - the prefix of S3 object keys (e.g. home/*). Default is "*".
      allowedActions - the set of S3 actions to allow. This parameter is required.
      Returns:
      The iam.PolicyStatement object, which can be used to apply e.g. conditions.

    • grantPut

      @Stability(Stable) @NotNull default Grant grantPut(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.

      If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.

      Specified by:
      grantPut in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantPutAcl

      @Stability(Stable) @NotNull default Grant grantPutAcl(@NotNull IGrantable identity, @Nullable String objectsKeyPattern)
      Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.

      If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, calling grantWrite(software.amazon.awscdk.services.iam.IGrantable,java.lang.Object) or grantReadWrite(software.amazon.awscdk.services.iam.IGrantable,java.lang.Object) no longer grants permissions to modify the ACLs of the objects; in this case, if you need to modify object ACLs, call this method explicitly.

      Specified by:
      grantPutAcl in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantRead

      @Stability(Stable) @NotNull default Grant grantRead(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

      If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.

      Specified by:
      grantRead in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantReadWrite

      @Stability(Stable) @NotNull default Grant grantReadWrite(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

      If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted. Before CDK version 1.85.0, this method granted the `s3:PutObject*` permission that included `s3:PutObjectAcl`, which could be used to grant read/write object access to IAM principals in other accounts. If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, and make sure the `@aws-cdk/aws-s3:grantWriteWithoutAcl` feature flag is set to `true` in the `context` key of your cdk.json file. If you've already updated, but still need the principal to have permissions to modify the ACLs, use the grantPutAcl(software.amazon.awscdk.services.iam.IGrantable,java.lang.String) method.

      Specified by:
      grantReadWrite in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantWrite

      @Stability(Stable) @NotNull default Grant grantWrite(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      Grant write permissions to this bucket to an IAM principal.

      If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal. Before CDK version 1.85.0, this method granted the `s3:PutObject*` permission that included `s3:PutObjectAcl`, which could be used to grant read/write object access to IAM principals in other accounts. If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, and make sure the `@aws-cdk/aws-s3:grantWriteWithoutAcl` feature flag is set to `true` in the `context` key of your cdk.json file. If you've already updated, but still need the principal to have permissions to modify the ACLs, use the grantPutAcl(software.amazon.awscdk.services.iam.IGrantable,java.lang.String) method.

      Specified by:
      grantWrite in interface IBucket
      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • onCloudTrailEvent

      @Stability(Stable) @NotNull default Rule onCloudTrailEvent(@NotNull String id, @Nullable OnCloudTrailBucketEventOptions options)
      Defines a CloudWatch event that triggers when something happens to this bucket.

      Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

      Specified by:
      onCloudTrailEvent in interface IBucket
      Parameters:
      id - The id of the rule. This parameter is required.
      options - Options for adding the rule.

    • onCloudTrailPutObject

      @Stability(Stable) @NotNull default Rule onCloudTrailPutObject(@NotNull String id, @Nullable OnCloudTrailBucketEventOptions options)
      Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call.

      Note that some tools like aws s3 cp will automatically use either PutObject or the multipart upload API depending on the file size, so using onCloudTrailWriteObject may be preferable.

      Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

      Specified by:
      onCloudTrailPutObject in interface IBucket
      Parameters:
      id - The id of the rule. This parameter is required.
      options - Options for adding the rule.

    • onCloudTrailWriteObject

      @Stability(Stable) @NotNull default Rule onCloudTrailWriteObject(@NotNull String id, @Nullable OnCloudTrailBucketEventOptions options)
      Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.

      This includes the events PutObject, CopyObject, and CompleteMultipartUpload.

      Note that some tools like aws s3 cp will automatically use either PutObject or the multipart upload API depending on the file size, so using this method may be preferable to onCloudTrailPutObject.

      Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

      Specified by:
      onCloudTrailWriteObject in interface IBucket
      Parameters:
      id - The id of the rule. This parameter is required.
      options - Options for adding the rule.

    • s3UrlForObject

      @Stability(Stable) @NotNull default String s3UrlForObject(@Nullable String key)
      The S3 URL of an S3 object.

      For example:

      • s3://onlybucket
      • s3://bucket/key

      Specified by:
      s3UrlForObject in interface IBucket
      Parameters:
      key - The S3 key of the object.
      Returns:
      an ObjectS3Url token

    • transferAccelerationUrlForObject

      @Stability(Stable) @NotNull default String transferAccelerationUrlForObject(@Nullable String key, @Nullable TransferAccelerationUrlOptions options)
      The https Transfer Acceleration URL of an S3 object.

      Specify dualStack: true at the options for dual-stack endpoint (connect to the bucket over IPv6). For example:

      • https://bucket.s3-accelerate.amazonaws.com
      • https://bucket.s3-accelerate.amazonaws.com/key

      Specified by:
      transferAccelerationUrlForObject in interface IBucket
      Parameters:
      key - The S3 key of the object.
      options - Options for generating URL.
      Returns:
      an TransferAccelerationUrl token

    • urlForObject

      @Stability(Stable) @NotNull default String urlForObject(@Nullable String key)
      The https URL of an S3 object. For example:.

      • https://s3.us-west-1.amazonaws.com/onlybucket
      • https://s3.us-west-1.amazonaws.com/bucket/key
      • https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey

      Specified by:
      urlForObject in interface IBucket
      Parameters:
      key - The S3 key of the object.
      Returns:
      an ObjectS3Url token

    • virtualHostedUrlForObject

      @Stability(Stable) @NotNull default String virtualHostedUrlForObject(@Nullable String key, @Nullable VirtualHostedStyleUrlOptions options)
      The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

      • https://only-bucket.s3.us-west-1.amazonaws.com
      • https://bucket.s3.us-west-1.amazonaws.com/key
      • https://bucket.s3.amazonaws.com/key
      • https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey

      Specified by:
      virtualHostedUrlForObject in interface IBucket
      Parameters:
      key - The S3 key of the object.
      options - Options for generating URL.
      Returns:
      an ObjectS3Url token