software.amazon.awscdk.core

Class AssetStaging

java.lang.Object

software.constructs.Construct

software.amazon.awscdk.core.Construct

software.amazon.awscdk.core.AssetStaging

All Implemented Interfaces:

IConstruct, IDependable

Direct Known Subclasses:

Staging

@Generated(value="jsii-pacmak/1.74.0 (build 6d08790)",
           date="2023-03-14T16:25:20.382Z")
public class AssetStaging
extends Construct

Stages a file or directory from a location on the file system into a staging directory.

This is controlled by the context key 'aws:cdk:asset-staging' and enabled by the CLI by default in order to ensure that when the CDK app exists, all assets are available for deployment. Otherwise, if an app references assets in temporary locations, those will not be available when it exists (see https://github.com/aws/aws-cdk/issues/1716).

The stagedPath property is a stringified token that represents the location of the file or directory after staging. It will be resolved only during the "prepare" stage and may be either the original path or the staged path depending on the context setting.

The file/directory are staged based on their content hash (fingerprint). This means that only if content was changed, copy will happen.

Example:

 // The code below shows an example of how to instantiate this type.
 // The values are placeholders you should change.
 import software.amazon.awscdk.core.*;
 DockerImage dockerImage;
 ILocalBundling localBundling;
 AssetStaging assetStaging = AssetStaging.Builder.create(this, "MyAssetStaging")
         .sourcePath("sourcePath")
         // the properties below are optional
         .assetHash("assetHash")
         .assetHashType(AssetHashType.SOURCE)
         .bundling(BundlingOptions.builder()
                 .image(dockerImage)
                 // the properties below are optional
                 .command(List.of("command"))
                 .entrypoint(List.of("entrypoint"))
                 .environment(Map.of(
                         "environmentKey", "environment"))
                 .local(localBundling)
                 .outputType(BundlingOutput.ARCHIVED)
                 .securityOpt("securityOpt")
                 .user("user")
                 .volumes(List.of(DockerVolume.builder()
                         .containerPath("containerPath")
                         .hostPath("hostPath")
                         // the properties below are optional
                         .consistency(DockerVolumeConsistency.CONSISTENT)
                         .build()))
                 .workingDirectory("workingDirectory")
                 .build())
         .exclude(List.of("exclude"))
         .extraHash("extraHash")
         .follow(SymlinkFollowMode.NEVER)
         .ignoreMode(IgnoreMode.GLOB)
         .build();
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AssetStaging.Builder A fluent builder for AssetStaging.

Nested classes/interfaces inherited from interface software.amazon.awscdk.core.IConstruct

IConstruct.Jsii$Default, IConstruct.Jsii$Proxy

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BUNDLING_INPUT_DIR The directory inside the bundling container into which the asset sources will be mounted.
static java.lang.String	BUNDLING_OUTPUT_DIR The directory inside the bundling container into which the bundled output should be written.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AssetStaging(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)
protected	AssetStaging(software.amazon.jsii.JsiiObjectRef objRef)
	AssetStaging(software.constructs.Construct scope, java.lang.String id, AssetStagingProps props)

Method Summary

Modifier and Type	Method and Description
static void	clearAssetHashCache() Clears the asset hash cache.
java.lang.String	getAbsoluteStagedPath() Absolute path to the asset data.
java.lang.String	getAssetHash() A cryptographic hash of the asset.
java.lang.Boolean	getIsArchive() Whether this asset is an archive (zip or jar).
FileAssetPackaging	getPackaging() How this asset should be packaged.
java.lang.String	getSourceHash() Deprecated. see `assetHash`.
java.lang.String	getSourcePath() The absolute path of the asset as it was referenced by the user.
java.lang.String	getStagedPath() Deprecated. - Use `absoluteStagedPath` instead.
java.lang.String	relativeStagedPath(Stack stack) Return the path to the staged asset, relative to the Cloud Assembly (manifest) directory of the given stack.

Methods inherited from class software.amazon.awscdk.core.Construct

getNode, isConstruct, onPrepare, onSynthesize, onValidate, prepare, synthesize, validate

Methods inherited from class java.lang.Object

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

Field Detail

BUNDLING_INPUT_DIR

public static final java.lang.String BUNDLING_INPUT_DIR

The directory inside the bundling container into which the asset sources will be mounted.

BUNDLING_OUTPUT_DIR

public static final java.lang.String BUNDLING_OUTPUT_DIR

The directory inside the bundling container into which the bundled output should be written.

Constructor Detail

AssetStaging

protected AssetStaging(software.amazon.jsii.JsiiObjectRef objRef)

AssetStaging

protected AssetStaging(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

AssetStaging

public AssetStaging(software.constructs.Construct scope,
                    java.lang.String id,
                    AssetStagingProps props)

Parameters:

scope - This parameter is required.

id - This parameter is required.

props - This parameter is required.

Method Detail

clearAssetHashCache

public static void clearAssetHashCache()

Clears the asset hash cache.

relativeStagedPath

public java.lang.String relativeStagedPath(Stack stack)

Return the path to the staged asset, relative to the Cloud Assembly (manifest) directory of the given stack.

Only returns a relative path if the asset was staged, returns an absolute path if it was not staged.

A bundled asset might end up in the outDir and still not count as "staged"; if asset staging is disabled we're technically expected to reference source directories, but we don't have a source directory for the bundled outputs (as the bundle output is written to a temporary directory). Nevertheless, we will still return an absolute path.

A non-obvious directory layout may look like this:

    CLOUD ASSEMBLY ROOT
      +-- asset.12345abcdef/
      +-- assembly-Stage
            +-- MyStack.template.json
            +-- MyStack.assets.json <- will contain { "path": "../asset.12345abcdef" }
 

Parameters:

stack - This parameter is required.

getAbsoluteStagedPath

public java.lang.String getAbsoluteStagedPath()

Absolute path to the asset data.

If asset staging is disabled, this will just be the source path or a temporary directory used for bundling.

If asset staging is enabled it will be the staged path.

IMPORTANT: If you are going to call addFileAsset(), use relativeStagedPath() instead.

getAssetHash

public java.lang.String getAssetHash()

A cryptographic hash of the asset.

getIsArchive

public java.lang.Boolean getIsArchive()

Whether this asset is an archive (zip or jar).

getPackaging

public FileAssetPackaging getPackaging()

How this asset should be packaged.

getSourceHash

@Deprecated
public java.lang.String getSourceHash()

Deprecated. see `assetHash`.

(deprecated) A cryptographic hash of the asset.

getSourcePath

public java.lang.String getSourcePath()

The absolute path of the asset as it was referenced by the user.

getStagedPath

@Deprecated
public java.lang.String getStagedPath()

Deprecated. - Use `absoluteStagedPath` instead.

(deprecated) Absolute path to the asset data.

If asset staging is disabled, this will just be the source path or a temporary directory used for bundling.

If asset staging is enabled it will be the staged path.

IMPORTANT: If you are going to call addFileAsset(), use relativeStagedPath() instead.