diff --git a/sdk/java/config/checkstyle/checkstyle.xml b/sdk/java/config/checkstyle/checkstyle.xml new file mode 100644 index 00000000000..53c9b747bd0 --- /dev/null +++ b/sdk/java/config/checkstyle/checkstyle.xml @@ -0,0 +1,43 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/sdk/java/config/checkstyle/suppressions.xml b/sdk/java/config/checkstyle/suppressions.xml new file mode 100644 index 00000000000..254d22dd348 --- /dev/null +++ b/sdk/java/config/checkstyle/suppressions.xml @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + diff --git a/sdk/java/pulumi/build.gradle b/sdk/java/pulumi/build.gradle index 6176399f638..6f22f377b6a 100644 --- a/sdk/java/pulumi/build.gradle +++ b/sdk/java/pulumi/build.gradle @@ -3,6 +3,7 @@ plugins { id("java-library") id("maven-publish") id("com.google.protobuf") version "0.9.4" + id("checkstyle") id("jacoco") } @@ -310,6 +311,17 @@ if (ossrhUsername) { } } +checkstyle { + toolVersion = "10.26.0" + configFile = file("${rootDir}/config/checkstyle/checkstyle.xml") +} +checkstyleMain { + source ='src/main/java' +} +checkstyleTest { + source ='src/test/java' +} + task exportKeyDependencies { doLast { diff --git a/sdk/java/pulumi/src/main/java/codegen/package-info.java b/sdk/java/pulumi/src/main/java/codegen/package-info.java new file mode 100644 index 00000000000..43b275048eb --- /dev/null +++ b/sdk/java/pulumi/src/main/java/codegen/package-info.java @@ -0,0 +1,6 @@ +/** + * Contains auto-generated classes and interfaces including gRPC services and protocol buffer messages. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package codegen; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/asset/Archive.java b/sdk/java/pulumi/src/main/java/com/pulumi/asset/Archive.java index 0b285f91146..23b71f70029 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/asset/Archive.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/asset/Archive.java @@ -13,6 +13,9 @@ protected Archive(String propName, Object value) { super(Constants.SpecialArchiveSig, propName, value); } + /** + * An InvalidArchive is internal class for uninitialized or invalid {@link Archive} + */ @InternalUse public static final class InvalidArchive extends Archive { public InvalidArchive() { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/asset/Asset.java b/sdk/java/pulumi/src/main/java/com/pulumi/asset/Asset.java index 7020b7021cb..06344168af2 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/asset/Asset.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/asset/Asset.java @@ -11,6 +11,9 @@ protected Asset(String propName, Object value) { super(Constants.SpecialAssetSig, propName, value); } + /** + * An InvalidAsset is an internal class for uninitialized or invalid {@link Asset} + */ @InternalUse public static final class InvalidAsset extends Asset { public InvalidAsset() { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/asset/AssetOrArchive.java b/sdk/java/pulumi/src/main/java/com/pulumi/asset/AssetOrArchive.java index 2baf21d4bd5..3ad59112f40 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/asset/AssetOrArchive.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/asset/AssetOrArchive.java @@ -19,6 +19,9 @@ protected AssetOrArchive(String sigKey, String propName, Object value) { this.value = requireNonNull(value); } + /** + * An AssetOrArchiveInternal is internal helper class of {@link AssetOrArchive}. + */ public static final class AssetOrArchiveInternal { private final AssetOrArchive assetOrArchive; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/asset/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/asset/package-info.java new file mode 100644 index 00000000000..be130c20ce4 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/asset/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides types for working with assets and archives. + */ +package com.pulumi.asset; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/internal/package-info.java new file mode 100644 index 00000000000..9241dce8733 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal event implementation details for the Pulumi Automation API. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.automation.events.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/package-info.java new file mode 100644 index 00000000000..bcc57d42d24 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/automation/events/package-info.java @@ -0,0 +1,5 @@ +/** + * Provides types describing Pulumi engine events, such as changes to resources or diagnostic messages, for use in the Pulumi Automation API. + */ + +package com.pulumi.automation.events; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/automation/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/automation/package-info.java new file mode 100644 index 00000000000..90283c3ce9e --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/automation/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides the Pulumi Automation API, the programmatic interface for driving Pulumi programs, encapsulating the functionality of the CLI. + */ +package com.pulumi.automation; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/SkipIfFalse.java b/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/SkipIfFalse.java index c933500aac1..659ccb171b0 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/SkipIfFalse.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/SkipIfFalse.java @@ -9,6 +9,9 @@ import com.pulumi.core.internal.annotations.InternalUse; +/** + * Annotation indicating that a boolean field should be skipped during serialization if its value is {@code false}. + */ @InternalUse @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.FIELD) diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/package-info.java new file mode 100644 index 00000000000..b442dacb650 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/automation/serialization/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal serialization utilities and implementation details for Pulumi Automation API. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.automation.serialization.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/bootstrap/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/bootstrap/internal/package-info.java new file mode 100644 index 00000000000..33d67a1a6f9 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/bootstrap/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal bootstrap utilities for plugin discovery and metadata management. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.bootstrap.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/codegen/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/codegen/internal/package-info.java new file mode 100644 index 00000000000..f51b28268d8 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/codegen/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Contains internal utilities for code generation and serialization + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.codegen.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/context/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/context/internal/package-info.java new file mode 100644 index 00000000000..de0e0d46c74 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/context/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal context implementation classes. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.context.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/context/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/context/package-info.java new file mode 100644 index 00000000000..9aac73683ae --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/context/package-info.java @@ -0,0 +1,5 @@ +/** + * Provides context interfaces for managing Pulumi program execution context, + * including configuration, logging, and runtime information. + */ +package com.pulumi.context; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/ResourceType.java b/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/ResourceType.java index 43825a7cae5..a8ec413a7e9 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/ResourceType.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/ResourceType.java @@ -5,6 +5,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Annotation to specify the Pulumi resource type and version for a resource class. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface ResourceType { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/package-info.java new file mode 100644 index 00000000000..5c7766f1a23 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/core/annotations/package-info.java @@ -0,0 +1,7 @@ +/** + * Provides annotations for resource and type metadata. + *

+ * This package contains Java annotations for marking resources, + * configuring metadata, and providing type information for Pulumi resources. + */ +package com.pulumi.core.annotations; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/annotations/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/annotations/package-info.java new file mode 100644 index 00000000000..c1df738a63c --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/annotations/package-info.java @@ -0,0 +1,6 @@ +/** + * Contains internal annotations and metadata utilities. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.core.internal.annotations; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/package-info.java new file mode 100644 index 00000000000..6380c4cae06 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/core/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal utilities and classes for core functionality. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.core.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/core/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/core/package-info.java new file mode 100644 index 00000000000..94db3a1cee5 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/core/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides core types and utility classes. + */ +package com.pulumi.core; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/CallOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/CallOptions.java index 1c0c71cb2df..b9ba01c847b 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/CallOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/CallOptions.java @@ -62,6 +62,10 @@ public Optional getVersion() { return Optional.ofNullable(version); } + /** + * Internal helper class for resolving the effective {@link ProviderResource} and {@link Resource} + * options + */ @InternalUse public static final class CallOptionsInternal { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/Deployment.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/Deployment.java index 39d6f92158b..4d4fcb84960 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/Deployment.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/Deployment.java @@ -15,6 +15,9 @@ import java.util.concurrent.CompletableFuture; import java.util.function.Supplier; +/** + * Provides the deployment context and core operations. + */ @InternalUse public interface Deployment extends ReadOrRegisterResource, RegisterResourceOutputs { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/DeploymentInstance.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/DeploymentInstance.java index aa406f992d3..5b6338b3c53 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/DeploymentInstance.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/DeploymentInstance.java @@ -4,6 +4,13 @@ import com.pulumi.core.internal.annotations.InternalUse; import com.pulumi.deployment.internal.DeploymentImpl; +/** + * An instance of a Pulumi deployment, providing access to deployment configuration, + * validity state, and lifecycle management for asynchronous operations. + * + * @see Deployment + * @see com.pulumi.deployment.internal.DeploymentImpl + */ public interface DeploymentInstance extends Deployment { @InternalUse DeploymentImpl.Config getConfig(); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOptions.java index cc5bc8cc749..3df43be7a30 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOptions.java @@ -89,6 +89,9 @@ public static Builder builder() { return new Builder(); } + /** + * The {@link InvokeOptions} builder. + */ public static final class Builder { private @Nullable Resource parent; private @Nullable ProviderResource provider; @@ -137,20 +140,49 @@ public InvokeOptions build() { } } + /** + * Internal utility class for advanced provider resolution logic within {@link InvokeOptions}. + * + * @see InvokeOptions + */ @InternalUse @ParametersAreNonnullByDefault public static final class InvokeOptionsInternal { + /** + * The underlying {@link InvokeOptions} instance from which provider and parent information is resolved. + */ private final InvokeOptions options; + /** + * Creates a new {@code InvokeOptionsInternal} wrapper for the given {@link InvokeOptions}. + * + * @param options the {@link InvokeOptions} instance to wrap; must not be null + * @throws NullPointerException if {@code options} is null + */ private InvokeOptionsInternal(InvokeOptions options) { this.options = requireNonNull(options); } + /** + * Creates a new {@code InvokeOptionsInternal} from the specified {@link InvokeOptions}. + * + * @param options the {@link InvokeOptions} to wrap + * @return a new {@code InvokeOptionsInternal} instance + * @throws NullPointerException if {@code options} is null + */ public static InvokeOptionsInternal from(InvokeOptions options) { return new InvokeOptionsInternal(options); } + /** + * Attempts to resolve a {@link ProviderResource} for the given provider token. + * + * @param token the provider token to resolve + * @return an {@link Optional} containing the resolved {@link ProviderResource}, or empty if not found + * + * @see ProviderResource + */ public Optional getNestedProvider(String token) { return this.options.getProvider().or( () -> this.options.getParent() diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOutputOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOutputOptions.java index 452b8285a9b..e266d46865d 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOutputOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/InvokeOutputOptions.java @@ -55,6 +55,9 @@ public List getDependsOn() { return this.dependsOn == null ? List.of() : new ArrayList<>(this.dependsOn); } + /** + * The {@link InvokeOutputOptions} builder. + */ public static final class Builder { private @Nullable Resource parent; private @Nullable ProviderResource provider; @@ -117,20 +120,52 @@ public InvokeOutputOptions build() { } } + /** + * Internal utility class of {@link InvokeOutputOptions}. + * + * @see InvokeOutputOptions + * @see ProviderResource + * @see com.pulumi.core.internal.Internal + */ @InternalUse @ParametersAreNonnullByDefault public static final class InvokeOutputOptionsInternal { + /** + * The underlying {@link InvokeOutputOptions} instance from which provider and parent information is resolved. + */ private final InvokeOutputOptions options; + /** + * Creates a new {@code InvokeOutputOptionsInternal} wrapper for the given {@link InvokeOutputOptions}. + * + * @param options the {@link InvokeOutputOptions} instance to wrap; must not be null + * @throws NullPointerException if {@code options} is null + */ private InvokeOutputOptionsInternal(InvokeOutputOptions options) { this.options = requireNonNull(options); } + /** + * Creates a new {@code InvokeOutputOptionsInternal} from the specified {@link InvokeOutputOptions}. + * + * @param options the {@link InvokeOutputOptions} to wrap + * @return a new {@code InvokeOutputOptionsInternal} instance + * @throws NullPointerException if {@code options} is null + */ public static InvokeOutputOptionsInternal from(InvokeOutputOptions options) { return new InvokeOutputOptionsInternal(options); } + /** + * Attempts to resolve a {@link ProviderResource} for the given provider token. + * + * @param token the provider token to resolve + * @return an {@link Optional} containing the resolved {@link ProviderResource}, or empty if not found + * + * @see ProviderResource + * @see com.pulumi.core.internal.Internal#from(Resource) + */ public Optional getNestedProvider(String token) { return this.options.getProvider().or( () -> this.options.getParent() diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/internal/package-info.java new file mode 100644 index 00000000000..b02c1c80465 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal deployment implementation for Pulumi stack deployment and resource management. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.deployment.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/deployment/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/package-info.java new file mode 100644 index 00000000000..f29e0e64a3f --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/deployment/package-info.java @@ -0,0 +1,7 @@ +/** + * Provides deployment management utilities and classes. + *

+ * This package contains utilities for managing Pulumi deployments, + * including stack operations and resource lifecycle management. + */ +package com.pulumi.deployment; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/exceptions/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/exceptions/package-info.java new file mode 100644 index 00000000000..f5b7dc0d462 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/exceptions/package-info.java @@ -0,0 +1,7 @@ +/** + * Provides exception types for error handling within the Pulumi SDK. + *

+ * This package contains custom exception classes and error handling + * utilities specific to Pulumi operations and resource management. + */ +package com.pulumi.exceptions; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/internal/PulumiInternal.java b/sdk/java/pulumi/src/main/java/com/pulumi/internal/PulumiInternal.java index 5b1118332ee..4e4b4091b8e 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/internal/PulumiInternal.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/internal/PulumiInternal.java @@ -28,31 +28,74 @@ import static java.util.Objects.requireNonNull; +/** + * Internal implementation of the {@link Pulumi} API, responsible for configuring and executing Pulumi stack deployments. + * + * @see com.pulumi.deployment.Deployment + * @see com.pulumi.deployment.internal.DeploymentImpl + * @see com.pulumi.resources.StackOptions + */ @InternalUse @ParametersAreNonnullByDefault public class PulumiInternal implements Pulumi, Pulumi.API { + /** + * The internal context representing the current stack execution environment. + */ protected final Runner runner; + /** + * The internal context representing the current stack execution environment. + */ protected final ContextInternal stackContext; + /** + * Constructs a new {@code PulumiInternal} instance with the specified runner and stack context. + * + * @param runner the runner used to execute deployment tasks + * @param stackContext the context representing the stack execution environment + * @throws NullPointerException if either argument is {@code null} + */ @InternalUse public PulumiInternal(Runner runner, ContextInternal stackContext) { this.runner = requireNonNull(runner); this.stackContext = requireNonNull(stackContext); } + /** + * Creates a new {@code PulumiInternal} instance using environment-based deployment configuration. + * + * @param options stack options to customize the deployment + * @return a configured {@code PulumiInternal} instance + * @see com.pulumi.resources.StackOptions + */ @InternalUse public static PulumiInternal fromEnvironment(StackOptions options) { var deployment = DeploymentImpl.fromEnvironment(); return completeConfiguration(deployment, options); } + /** + * Creates a new {@code PulumiInternal} instance using inline deployment settings. + * + * @param settings inline deployment settings + * @param options stack options to customize the deployment + * @return a configured {@code PulumiInternal} instance + * @see com.pulumi.deployment.internal.InlineDeploymentSettings + * @see com.pulumi.resources.StackOptions + */ @InternalUse public static PulumiInternal fromInline(InlineDeploymentSettings settings, StackOptions options) { var deployment = DeploymentImpl.fromInline(settings); return completeConfiguration(deployment, options); } + /** + * Completes the configuration of a {@code PulumiInternal} instance by initializing context and dependencies. + * + * @param deployment the deployment implementation to use + * @param options stack options to customize the deployment + * @return a fully configured {@code PulumiInternal} instance + */ private static PulumiInternal completeConfiguration(DeploymentImpl deployment, StackOptions options) { var instance = Deployment.getInstance(); var organizationName = deployment.getOrganizationName(); @@ -73,14 +116,36 @@ private static PulumiInternal completeConfiguration(DeploymentImpl deployment, S return new PulumiInternal(runner, ctx); } + /** + * Runs the Pulumi stack synchronously, blocking until completion and exiting the process with the result code. + * + * @param stack a {@link Consumer} that receives the Pulumi {@link Context} for stack logic execution + * @see com.pulumi.Context + */ public void run(Consumer stack) { System.exit(runAsync(stack).join()); } + /** + * Runs the Pulumi stack asynchronously, returning a future for the exit code. + * + * @param stackCallback a {@link Consumer} that receives the Pulumi {@link Context} for stack logic execution + * @return a {@link CompletableFuture} that completes with the process exit code + */ public CompletableFuture runAsync(Consumer stackCallback) { return runAsyncResult(stackCallback).thenApply(r -> r.exitCode()); } + /** + * Runs the Pulumi stack inline with a custom asynchronous runner function. + * + * @param runnerFunc a function that receives the Pulumi {@link Context} and returns a future result + * @param the type of the result produced by the runner function + * @return a {@link CompletableFuture} that completes with the runner function's result + * @throws RuntimeException if multiple exceptions occur during execution + * @throws IllegalStateException if no result or exceptions are available + * @see com.pulumi.Context + */ @InternalUse public CompletableFuture runInlineAsync(Function> runnerFunc) { return runner.runAsync(() -> runnerFunc.apply(stackContext)) @@ -102,6 +167,14 @@ public CompletableFuture runInlineAsync(Function> runAsyncResult(Consumer stackCallback) { // Stack must be created and set globally before running any user code return runner.runAsync( diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/internal/package-info.java new file mode 100644 index 00000000000..b4bceba404e --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal implementation classes. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/package-info.java new file mode 100644 index 00000000000..84d2ba88cd3 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/package-info.java @@ -0,0 +1,4 @@ +/** + * Main package for the Pulumi Java SDK. + */ +package com.pulumi; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProvider.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProvider.java index 51effb97330..9e2c773d4cf 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProvider.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProvider.java @@ -23,6 +23,9 @@ import com.pulumi.resources.ComponentResource; import com.pulumi.resources.ComponentResourceOptions; +/** + * A generic provider implementation for component resources. + */ public class ComponentProvider implements Provider { private final Metadata metadata; private final String basePackageName; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProviderHost.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProviderHost.java index 416757c6773..1b54464d9e2 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProviderHost.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ComponentProviderHost.java @@ -3,15 +3,37 @@ import java.io.IOException; import java.util.ArrayList; +/** + * A host for a component provider, managing its lifecycle and integration. + */ public class ComponentProviderHost { + /** + * Metadata describing the provider, such as its name and version. + */ private final Metadata metadata; + /** + * The Java package containing the component resources for this provider. + */ private final Package currentPackage; + /** + * Constructs a new {@code ComponentProviderHost} with the specified provider name and package. + * + * @param name the name of the provider + * @param currentPackage the Java package containing the component resources + */ public ComponentProviderHost(String name, Package currentPackage) { this.metadata = new Metadata(name); this.currentPackage = currentPackage; } + /** + * Starts the component provider host, initializing the provider and gRPC server. + * + * @param args the command-line arguments passed to the provider + * @throws IOException if an I/O error occurs while starting the server + * @throws InterruptedException if the server is interrupted while running + */ public void start(String[] args) throws IOException, InterruptedException { String engineAddress; try { @@ -28,6 +50,13 @@ public void start(String[] args) throws IOException, InterruptedException { server.startAndBlockUntilShutdown(); } + /** + * Extracts and validates the engine address from the command-line arguments. + * + * @param args the command-line arguments + * @return the engine address as a string + * @throws IllegalArgumentException if no engine address is provided or multiple non-logging arguments are found + */ static String getEngineAddress(String[] args) { var cleanArgs = new ArrayList(); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ErrorHandlingInterceptor.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ErrorHandlingInterceptor.java index d8892281770..cbc2e00ed35 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ErrorHandlingInterceptor.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ErrorHandlingInterceptor.java @@ -4,6 +4,12 @@ import java.io.PrintWriter; import java.io.StringWriter; +/** + * A gRPC {@link ServerInterceptor} that catches and reports uncaught exceptions as internal errors. + * + * @see io.grpc.ServerInterceptor + * @see io.grpc.Status + */ public class ErrorHandlingInterceptor implements ServerInterceptor { @Override public ServerCall.Listener interceptCall( diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Metadata.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Metadata.java index 6b4a53ed0ea..e320c3e18af 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Metadata.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Metadata.java @@ -1,18 +1,53 @@ package com.pulumi.provider.internal; +/** + * Represents metadata information for a Pulumi provider package. + * + * @see com.pulumi.provider.internal.ComponentProvider + */ public class Metadata { + /** + * The unique name of the provider package. + */ private final String name; + /** + * The version of the provider package. + */ private final String version; + /** + * The human-readable display name for the provider package, or {@code null} if not specified. + */ private final String displayName; + /** + * Constructs a new {@code Metadata} instance with the specified name and default version/display name. + * + * @param name the unique name of the provider package + * @throws IllegalArgumentException if {@code name} is null or empty + */ public Metadata(String name) { this(name, "0.0.0", null); } + /** + * Constructs a new {@code Metadata} instance with the specified name and version. + * + * @param name the unique name of the provider package + * @param version the version of the provider package + * @throws IllegalArgumentException if {@code name} or {@code version} is null or empty + */ public Metadata(String name, String version) { this(name, version, null); } + /** + * Constructs a new {@code Metadata} instance with the specified name, version, and display name. + * + * @param name the unique name of the provider package + * @param version the version of the provider package + * @param displayName the human-readable display name, or {@code null} if not specified + * @throws IllegalArgumentException if {@code name} or {@code version} is null or empty + */ public Metadata(String name, String version, String displayName) { if (name == null || name.isEmpty()) { throw new IllegalArgumentException("Name cannot be null or empty"); @@ -25,14 +60,29 @@ public Metadata(String name, String version, String displayName) { this.displayName = displayName; } + /** + * Gets the unique name of the provider package. + * + * @return the provider name + */ public String getName() { return name; } + /** + * Gets the version of the provider package. + * + * @return the provider version + */ public String getVersion() { return version; } + /** + * Gets the human-readable display name for the provider package, or {@code null} if not specified. + * + * @return the display name, or {@code null} + */ public String getDisplayName() { return displayName; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Provider.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Provider.java index 64f617bd265..610230f7aca 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Provider.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/Provider.java @@ -4,6 +4,9 @@ import com.pulumi.provider.internal.models.*; +/** + * An interface representing Pulumi Provider that can be configured, provide schemas, and construct resources. + */ public interface Provider { /** * Configure the provider with the given configuration parameters. diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ResourceProviderService.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ResourceProviderService.java index 2fca03cea56..5328092276d 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ResourceProviderService.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/ResourceProviderService.java @@ -27,24 +27,59 @@ import com.pulumi.resources.StackOptions; import com.pulumi.resources.internal.DependencyProviderResource; +/** + * The {@code ResourceProviderService} class is responsible for managing the lifecycle of resource provider server. + * + * @see Provider + * @see ResourceProviderService.ResourceProviderImpl + */ public class ResourceProviderService { private static final Logger logger = Logger.getLogger(ResourceProviderService.class.getName()); + /** + * The gRPC server instance that serves the resource provider. + */ Server server; // Exposed as private-package for testing. + + /** + * The address of the Pulumi engine to which this provider service connects. + */ private final String engineAddress; + + /** + * The provider implementation that contains the logic for handling resource operations. + */ private final Provider implementation; + /** + * Constructs a new {@code ResourceProviderService} with the specified engine address and provider implementation. + * @param engineAddress the address of the Pulumi engine to connect to + * @param implementation the provider implementation to expose via the gRPC server + */ public ResourceProviderService(String engineAddress, Provider implementation) { this.engineAddress = engineAddress; this.implementation = implementation; } + /** + * Starts the resource provider server and blocks the current thread until the server is shut down. + * @throws IOException if the server fails to start due to I/O errors + * @throws InterruptedException if the thread is interrupted while waiting for shutdown + * + * @see #start() + * @see #blockUntilShutdown() + */ public void startAndBlockUntilShutdown() throws IOException, InterruptedException { start(); blockUntilShutdown(); } + /** + * Starts the gRPC server for the resource provider, making it available to handle requests from the engine. + * + * @throws IOException if the server fails to start due to I/O errors + */ void start() throws IOException { server = createServerBuilder() .addService(new ResourceProviderImpl(this.engineAddress, this.implementation)) @@ -67,18 +102,32 @@ public void run() { }); } + /** + * Stops the gRPC server, preventing it from handling any further requests. + * + * @throws InterruptedException if the thread is interrupted while waiting for shutdown + */ private void stop() throws InterruptedException { if (server != null) { server.shutdown().awaitTermination(30, TimeUnit.SECONDS); } } + /** + * Blocks the current thread until the gRPC server is shut down. + * @throws InterruptedException if the thread is interrupted while waiting for shutdown + */ private void blockUntilShutdown() throws InterruptedException { if (server != null) { server.awaitTermination(); } } + /** + * Creates a new {@link ServerBuilder} instance for configuring and building the gRPC server. + * + * @return a {@link ServerBuilder} instance for configuring the server + */ protected ServerBuilder createServerBuilder() { return ServerBuilder.forPort(0); } @@ -241,6 +290,11 @@ private void handleCompletion(Throwable error, T response, DeploymentInstanceHolder.internalUnsafeDestroyInstance(); } + /** + * Deserializes the custom timeouts from the protobuf representation. + * @param customTimeouts the protobuf representation of custom timeouts + * @return a {@link CustomTimeouts} instance with the parsed timeouts + */ private static CustomTimeouts deserializeTimeouts(pulumirpc.Provider.ConstructRequest.CustomTimeouts customTimeouts) { return CustomTimeouts.builder() @@ -250,6 +304,11 @@ private static CustomTimeouts deserializeTimeouts(pulumirpc.Provider.ConstructRe .build(); } + /** + * Unmarshals the properties from a protobuf {@link Struct} into a map of {@link PropertyValue}. + * @param properties the protobuf representation of properties + * @return a map of property names to their corresponding {@link PropertyValue} + */ private static Map unmarshal(Struct properties) { if (properties == null) { return Collections.emptyMap(); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/ComponentAnalyzer.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/ComponentAnalyzer.java index acecf34d4db..2398c358eed 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/ComponentAnalyzer.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/ComponentAnalyzer.java @@ -27,6 +27,11 @@ import java.util.TreeSet; import java.util.Set; +/** + * Analyzes Pulumi component resource classes to generate a provider schema. + * @see com.pulumi.provider.internal.schema.PackageSpec + * @see com.pulumi.resources.ComponentResource + */ public final class ComponentAnalyzer { private final Metadata metadata; private final Map typeDefinitions = new HashMap<>(); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/package-info.java new file mode 100644 index 00000000000..40e2fc62b98 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/infer/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal utilities for inferring resource schemas, metadata, and type information. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.provider.internal.infer; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureRequest.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureRequest.java index db935a696ac..d5a167a848b 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureRequest.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureRequest.java @@ -4,12 +4,39 @@ import com.pulumi.provider.internal.properties.PropertyValue; +/** + * Represents a configuration request for a provider. + */ public class ConfigureRequest { + + /** + * The environment variables available to the provider. + */ private final Map variables; + + /** + * The configuration arguments provided to the provider. + */ private final Map args; + + /** + * Indicates whether the provider should accept secret values in configuration. + */ private final boolean acceptSecrets; + + /** + * Indicates whether the provider should accept resource references in configuration. + */ private final boolean acceptResources; + /** + * Constructs a new {@code ConfigureRequest} with the specified variables, arguments, and feature flags. + * + * @param variables the environment variables available to the provider + * @param args the configuration arguments provided to the provider + * @param acceptSecrets whether the provider should accept secret values + * @param acceptResources whether the provider should accept resource references + */ public ConfigureRequest(Map variables, Map args, boolean acceptSecrets, boolean acceptResources) { this.variables = variables; @@ -18,18 +45,38 @@ public ConfigureRequest(Map variables, Map getVariables() { return variables; } + /** + * Gets the configuration arguments provided to the provider. + * + * @return a map of argument names to {@link PropertyValue} instances + */ public Map getArgs() { return args; } + /** + * Indicates whether the provider should accept secret values in configuration. + * + * @return {@code true} if secrets are accepted, {@code false} otherwise + */ public boolean isAcceptSecrets() { return acceptSecrets; } + /** + * Indicates whether the provider should accept resource references in configuration. + * + * @return {@code true} if resource references are accepted, {@code false} otherwise + */ public boolean isAcceptResources() { return acceptResources; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureResponse.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureResponse.java index ca19c7d910d..c673a143bd1 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureResponse.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConfigureResponse.java @@ -1,11 +1,34 @@ package com.pulumi.provider.internal.models; +/** + * Represents the response to a configuration request for a provider. + */ public class ConfigureResponse { + /** + * Indicates whether the provider accepts secret values in its configuration and resource properties. + */ private final boolean acceptSecrets; + /** + * Indicates whether the provider supports preview operations. + */ private final boolean supportsPreview; + /** + * Indicates whether the provider accepts resource references in its configuration. + */ private final boolean acceptResources; + /** + * Indicates whether the provider accepts output values in its configuration. + */ private final boolean acceptOutputs; + /** + * Constructs a new {@code ConfigureResponse} with the specified feature flags. + * + * @param acceptSecrets whether the provider accepts secret values + * @param supportsPreview whether the provider supports preview operations + * @param acceptResources whether the provider accepts resource references + * @param acceptOutputs whether the provider accepts output values + */ public ConfigureResponse(boolean acceptSecrets, boolean supportsPreview, boolean acceptResources, boolean acceptOutputs) { this.acceptSecrets = acceptSecrets; @@ -14,18 +37,38 @@ public ConfigureResponse(boolean acceptSecrets, boolean supportsPreview, this.acceptOutputs = acceptOutputs; } + /** + * Indicates whether the provider accepts secret values in its configuration and resource properties. + * + * @return {@code true} if secrets are accepted, {@code false} otherwise + */ public boolean isAcceptSecrets() { return acceptSecrets; } + /** + * Indicates whether the provider supports preview operations. + * + * @return {@code true} if preview is supported, {@code false} otherwise + */ public boolean isSupportsPreview() { return supportsPreview; } + /** + * Indicates whether the provider accepts resource references in its configuration. + * + * @return {@code true} if resource references are accepted, {@code false} otherwise + */ public boolean isAcceptResources() { return acceptResources; } + /** + * Indicates whether the provider accepts output values in its configuration. + * + * @return {@code true} if output values are accepted, {@code false} otherwise + */ public boolean isAcceptOutputs() { return acceptOutputs; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructRequest.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructRequest.java index 9b46388e653..303abd0caf0 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructRequest.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructRequest.java @@ -5,12 +5,39 @@ import com.pulumi.provider.internal.properties.PropertyValue; import com.pulumi.resources.ComponentResourceOptions; +/** + * Represents a request to construct a new component resource in a Pulumi provider. + */ public class ConstructRequest { + + /** + * The fully qualified type token of the resource to construct (e.g., {@code "my:module:ResourceType"}). + */ private final String type; + + /** + * The logical name to assign to the constructed resource. + */ private final String name; + + /** + * The input properties for the resource, as a map from property names to values. + */ private final Map inputs; + + /** + * The options to use when constructing the component resource (e.g., parent, dependencies). + */ private final ComponentResourceOptions options; + /** + * Constructs a new {@code ConstructRequest} with the specified type, name, inputs, and options. + * + * @param type the fully qualified type token of the resource to construct + * @param name the logical name to assign to the constructed resource + * @param inputs the input properties for the resource + * @param options the options to use when constructing the component resource + */ public ConstructRequest(String type, String name, Map inputs, ComponentResourceOptions options) { this.type = type; @@ -19,18 +46,38 @@ public ConstructRequest(String type, String name, Map inp this.options = options; } + /** + * Gets the fully qualified type token of the resource to construct. + * + * @return the resource type token + */ public String getType() { return type; } + /** + * Get the logical name to assign to the constructed resource. + * + * @return the resource name + */ public String getName() { return name; } + /** + * Get the input properties for the resource. + * + * @return a map of property names to {@link PropertyValue} instances + */ public Map getInputs() { return inputs; } + /** + * Get the options to use when constructing the component resource. + * + * @return the {@link ComponentResourceOptions} instance + */ public ComponentResourceOptions getOptions() { return options; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructResponse.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructResponse.java index a83831d44ba..361856382d9 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructResponse.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/ConstructResponse.java @@ -5,25 +5,62 @@ import com.pulumi.provider.internal.properties.PropertyValue; +/** + * Represents the response to a construct request for a component resource. + */ public class ConstructResponse { + + /** + * The URN of the constructed resource. + */ private final String urn; + + /** + * The output state of the constructed resource, as a map from property names to values. + */ private final Map state; + + /** + * The dependencies for each output property, as a map from property names to sets of dependent URNs. + */ private final Map> stateDependencies; + /** + * Constructs a new {@code ConstructResponse} with the specified URN, state, and state dependencies. + * + * @param urn the URN of the constructed resource + * @param state the output state of the resource + * @param stateDependencies the dependencies for each output property + */ public ConstructResponse(String urn, Map state, Map> stateDependencies) { this.urn = urn; this.state = state; this.stateDependencies = stateDependencies; } + /** + * Get the URN of the constructed resource. + * + * @return the resource URN + */ public String getUrn() { return urn; } + /** + * Get the output state of the constructed resource. + * + * @return a map of property names to {@link PropertyValue} instances + */ public Map getState() { return state; } + /** + * Get the dependencies for each output property. + * + * @return a map from property names to sets of dependent URNs + */ public Map> getStateDependencies() { return stateDependencies; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaRequest.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaRequest.java index 7ed601e3523..65aabeff5aa 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaRequest.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaRequest.java @@ -1,24 +1,63 @@ package com.pulumi.provider.internal.models; +/** + * Represents a request to retrieve the schema for a provider or one of its subpackages. + * + * @see GetSchemaResponse + */ public class GetSchemaRequest { + + /** + * The version of the schema being requested. + */ private final int version; + + /** + * The name of the subpackage for which the schema is requested, or {@code null} for the main package. + */ private final String subpackageName; + + /** + * The version of the subpackage being requested, or {@code null} if not applicable. + */ private final String subpackageVersion; + /** + * Constructs a new {@code GetSchemaRequest} with the specified version and subpackage details. + * + * @param version the version of the schema being requested + * @param subpackageName the name of the subpackage, or {@code null} for the main package + * @param subpackageVersion the version of the subpackage, or {@code null} if not applicable + */ public GetSchemaRequest(int version, String subpackageName, String subpackageVersion) { this.version = version; this.subpackageName = subpackageName; this.subpackageVersion = subpackageVersion; } + /** + * Gets the version of the schema being requested. + * + * @return the schema version + */ public int getVersion() { return version; } + /** + * Gets the name of the subpackage for which the schema is requested. + * + * @return the subpackage name, or {@code null} for the main package + */ public String getSubpackageName() { return subpackageName; } + /** + * Gets the version of the subpackage being requested. + * + * @return the subpackage version, or {@code null} if not applicable + */ public String getSubpackageVersion() { return subpackageVersion; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaResponse.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaResponse.java index b713ab3cf64..c164dead22f 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaResponse.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/GetSchemaResponse.java @@ -1,12 +1,30 @@ package com.pulumi.provider.internal.models; +/** + * Represents the response to a schema request for a Pulumi provider or subpackage. + * + * @see GetSchemaRequest + */ public class GetSchemaResponse { + /** + * The JSON schema definition returned by the provider. + */ private final String schema; + /** + * Constructs a new {@code GetSchemaResponse} with the specified schema definition. + * + * @param schema the JSON schema definition as a string + */ public GetSchemaResponse(String schema) { this.schema = schema; } + /** + * Gets the JSON schema definition returned by the provider. + * + * @return the schema definition as a string + */ public String getSchema() { return schema; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/package-info.java new file mode 100644 index 00000000000..762392a8c2c --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/models/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal provider protocol models for Pulumi. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.provider.internal.models; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/package-info.java new file mode 100644 index 00000000000..90d2fcd125b --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal provider support utilities for Pulumi. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.provider.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/PropertyValue.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/PropertyValue.java index f44c1fa9ff7..beb1321fc0f 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/PropertyValue.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/PropertyValue.java @@ -16,7 +16,19 @@ import com.pulumi.asset.*; import com.pulumi.core.internal.Constants; +/** + * Represents a value in provider property system, supporting a wide range of types and + * serialization to and from Protobuf values. + */ public class PropertyValue { + + /** + * Enum representing the type of value stored in a {@link PropertyValue}. + *

+ * Each type corresponds to a specific Java class, allowing for type-safe access to the value. + * The {@code NULL} and {@code COMPUTED} types are special cases that do not hold a value. + *

+ */ public enum ValueType { NULL(null), BOOL(Boolean.class), @@ -38,6 +50,9 @@ public enum ValueType { } } + /** + * Represents a reference to a Pulumi resource, including its URN, ID, and package version. + */ public static class ResourceReference { private final String URN; private final PropertyValue id; @@ -65,6 +80,9 @@ public int hashCode() { } } + /** + * Represents a reference to an output value, including its dependencies. + */ public static class OutputReference { private final PropertyValue value; private final Set dependencies; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/package-info.java new file mode 100644 index 00000000000..a17042214ff --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/properties/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal property serialization and deserialization utilities for providers. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.provider.internal.properties; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/BuiltinTypeSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/BuiltinTypeSpec.java index 59bf1eb50f2..805778a7c02 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/BuiltinTypeSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/BuiltinTypeSpec.java @@ -1,5 +1,9 @@ package com.pulumi.provider.internal.schema; +/** + * Defines constant values for the built-in types supported by the provider schema. + * @see com.pulumi.provider.internal.schema.TypeSpec + */ public final class BuiltinTypeSpec { public static final String STRING = "string"; public static final String INTEGER = "integer"; @@ -7,5 +11,8 @@ public final class BuiltinTypeSpec { public static final String BOOLEAN = "boolean"; public static final String OBJECT = "object"; + /** + * Private constructor to prevent instantiation of this utility class. + */ private BuiltinTypeSpec() {} // Prevent instantiation -} \ No newline at end of file +} diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ComplexTypeSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ComplexTypeSpec.java index 78065eb83d7..357525da986 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ComplexTypeSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ComplexTypeSpec.java @@ -4,7 +4,20 @@ import java.util.Map; import java.util.Set; +/** + * Represents a complex type specification within the Pulumi provider schema. + * @see ObjectTypeSpec + * @see PropertySpec + */ public class ComplexTypeSpec extends ObjectTypeSpec { + + /** + * Constructs a new {@code ComplexTypeSpec} with the specified type, properties, and required fields. + * + * @param type the type name + * @param properties a map of property names to their specifications + * @param required a set of required property names + */ private ComplexTypeSpec( String type, Map properties, @@ -13,10 +26,23 @@ private ComplexTypeSpec( super(type, properties, required); } + /** + * Creates a {@code ComplexTypeSpec} with the given type and no properties or required fields. + * + * @param type the type name + * @return a new {@code ComplexTypeSpec} instance with the specified type + */ public static ComplexTypeSpec of(String type) { return new ComplexTypeSpec(type, null, null); } + /** + * Creates a {@code ComplexTypeSpec} for an object type with the specified properties and required fields. + * + * @param properties a map of property names to their specifications + * @param required a set of required property names + * @return a new {@code ComplexTypeSpec} instance + */ public static ComplexTypeSpec ofObject( Map properties, Set required diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ObjectTypeSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ObjectTypeSpec.java index e6d5eee9246..932f9c683e9 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ObjectTypeSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ObjectTypeSpec.java @@ -7,6 +7,12 @@ import java.util.Set; import java.util.TreeSet; +/** + * Represents the specification for an object type in provider schema. + * + * @see PropertySpec + * @see ComplexTypeSpec + */ public class ObjectTypeSpec { @SerializedName("type") private String type; @@ -17,6 +23,13 @@ public class ObjectTypeSpec { @SerializedName("required") private Set required; + /** + * Constructs a new {@code ObjectTypeSpec} with the specified type, properties, and required fields. + * + * @param type the type name (typically {@code "object"}) + * @param properties a map of property names to their specifications + * @param required a set of required property names + */ protected ObjectTypeSpec( String type, Map properties, @@ -27,18 +40,39 @@ protected ObjectTypeSpec( this.required = new TreeSet<>(required); } + /** + * Gets the type name of this object specification. + * + * @return the type name + */ public String getType() { return type; } + /** + * Gets the map of property names to their specifications for this object type. + * + * @return a map of property names to {@link PropertySpec} instances, or {@code null} if not defined + */ public Map getProperties() { return properties; } + /** + * Gets the set of required property names for this object type. + * + * @return a set of required property names, or {@code null} if not defined + */ public Set getRequired() { return required; } + /** + * Compares this object type specification to another for equality. + * + * @param o the object to compare with + * @return {@code true} if the objects are equal, {@code false} otherwise + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -49,11 +83,21 @@ public boolean equals(Object o) { Objects.equals(required, that.required); } + /** + * Computes the hash code for this object type specification. + * + * @return the hash code value + */ @Override public int hashCode() { return Objects.hash(type, properties, required); } + /** + * Returns a string representation of this object type specification. + * + * @return a string describing the object type specification + */ @Override public String toString() { return "ObjectTypeSpec{" + diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PackageSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PackageSpec.java index 5c4239e3a9c..c5e4c4cc7d7 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PackageSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PackageSpec.java @@ -5,6 +5,12 @@ import java.util.Map; import java.util.Objects; +/** + * Represents the specification for a provider package schema. + * + * @see ResourceSpec + * @see ComplexTypeSpec + */ public class PackageSpec { @SerializedName("name") private String name; @@ -27,69 +33,152 @@ public class PackageSpec { @SerializedName("language") private Map> language = new HashMap<>(); + /** + * Sets the name of the provider package. + * + * @param name the package name + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setName(String name) { this.name = name; return this; } + /** + * Sets the namespace for the provider package. + * + * @param namespace the namespace for code generation and organization + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setNamespace(String namespace) { this.namespace = namespace; return this; } + /** + * Sets the human-readable display name for the provider package. + * + * @param displayName the display name + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setDisplayName(String displayName) { this.displayName = displayName; return this; } + /** + * Sets the version of the provider package. + * + * @param version the version string + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setVersion(String version) { this.version = version; return this; } + /** + * Sets the resource specifications for this package. + * + * @param resources a map of resource names to their specifications + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setResources(Map resources) { this.resources = resources; return this; } + /** + * Sets the complex type specifications for this package. + * + * @param types a map of complex type names to their specifications + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setTypes(Map types) { this.types = types; return this; } + /** + * Sets the language-specific configuration for this package. + * + * @param language a map keyed by language name, each containing language-specific options + * @return this {@code PackageSpec} instance for method chaining + */ public PackageSpec setLanguage(Map> language) { this.language = language; return this; } + /** + * Gets the name of the provider package. + * + * @return the package name + */ public String getName() { return name; } + /** + * Gets the namespace for the provider package. + * + * @return the namespace + */ public String getNamespace() { return namespace; } + /** + * Gets the human-readable display name for the provider package. + * + * @return the display name + */ public String getDisplayName() { return displayName; } + /** + * Gets the version of the provider package. + * + * @return the version string + */ public String getVersion() { return version; } + /** + * Gets the resource specifications for this package. + * + * @return a map of resource names to their specifications + */ public Map getResources() { return resources; } + /** + * Gets the complex type specifications for this package. + * + * @return a map of complex type names to their specifications + */ public Map getTypes() { return types; } + /** + * Gets the language-specific configuration for this package. + * + * @return a map keyed by language name, each containing language-specific options + */ public Map> getLanguage() { return language; } + /** + * Compares this package specification to another for equality. + * + * @param o the object to compare with + * @return {@code true} if the objects are equal, {@code false} otherwise + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -103,11 +192,21 @@ public boolean equals(Object o) { Objects.equals(language, that.language); } + /** + * Computes the hash code for this package specification. + * + * @return the hash code value + */ @Override public int hashCode() { return Objects.hash(name, displayName, version, resources, types, language); } + /** + * Returns a string representation of this package specification. + * + * @return a string describing the package specification + */ @Override public String toString() { return "PackageSpec{" + diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PropertySpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PropertySpec.java index 30d5a987743..edd6250ec44 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PropertySpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/PropertySpec.java @@ -1,34 +1,94 @@ package com.pulumi.provider.internal.schema; +/** + * Represents the specification for a property in a provider schema object. + * + * @see TypeSpec + * @see ComplexTypeSpec + */ public class PropertySpec extends TypeSpec { + + /** + * Constructs a new {@code PropertySpec} with the specified type, reference, and additional type details. + * + * @param type the type name + * @param ref the reference to another type + * @param plain whether the property is a plain type + * @param items the item type if this property is an array + * @param additionalProperties the type of values if this property is a dictionary + */ public PropertySpec(String type, String ref, Boolean plain, TypeSpec items, TypeSpec additionalProperties) { super(type, ref, plain, items, additionalProperties); } + /** + * Creates a {@code PropertySpec} for a built-in type. + * + * @param type the built-in type name + * @return a new {@code PropertySpec} instance for the specified built-in type + */ public static PropertySpec ofBuiltin(String type) { return ofBuiltin(type, null); } + /** + * Creates a {@code PropertySpec} for a built-in type with an optional plain flag. + * + * @param type the built-in type name + * @param plain whether the property is a plain type (may be {@code null}) + * @return a new {@code PropertySpec} instance for the specified built-in type + */ public static PropertySpec ofBuiltin(String type, Boolean plain) { return new PropertySpec(type, null, plain, null, null); } + /** + * Creates a {@code PropertySpec} for a reference to another type. + * + * @param ref the reference to another type + * @return a new {@code PropertySpec} instance referencing the specified type + */ public static PropertySpec ofRef(String ref) { return ofRef(ref, null); } + /** + * Creates a {@code PropertySpec} for a reference to another type with an optional plain flag. + * + * @param ref the reference to another type + * @param plain whether the property is a plain type (may be {@code null}) + * @return a new {@code PropertySpec} instance referencing the specified type + */ public static PropertySpec ofRef(String ref, Boolean plain) { return new PropertySpec(null, ref, plain, null, null); } + /** + * Creates a {@code PropertySpec} for an array property with the specified item type. + * + * @param items the type specification for array items + * @return a new {@code PropertySpec} instance representing an array of the specified item type + */ public static PropertySpec ofArray(TypeSpec items) { return new PropertySpec("array", null, null, items, null); } + /** + * Creates a {@code PropertySpec} for a dictionary property with the specified value type. + * + * @param additionalProperties the type specification for dictionary values + * @return a new {@code PropertySpec} instance representing a dictionary with the specified value type + */ public static PropertySpec ofDict(TypeSpec additionalProperties) { return new PropertySpec("object", null, null, null, additionalProperties); } + /** + * Compares this property specification to another for equality. + * + * @param o the object to compare with + * @return {@code true} if the objects are equal, {@code false} otherwise + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -36,11 +96,21 @@ public boolean equals(Object o) { return super.equals(o); } + /** + * Computes the hash code for this property specification. + * + * @return the hash code value + */ @Override public int hashCode() { return super.hashCode(); } + /** + * Returns a string representation of this property specification. + * + * @return a string describing the property specification + */ @Override public String toString() { return "PropertySpec" + super.toString(); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ResourceSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ResourceSpec.java index 58ae4efd657..c2ed2f6cb5c 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ResourceSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/ResourceSpec.java @@ -8,6 +8,12 @@ import java.util.Set; import java.util.TreeSet; +/** + * Represents the specification for a resource in a provider schema. + * + * @see ObjectTypeSpec + * @see PropertySpec + */ public class ResourceSpec extends ObjectTypeSpec { @SerializedName("isComponent") private boolean isComponent; @@ -18,6 +24,14 @@ public class ResourceSpec extends ObjectTypeSpec { @SerializedName("requiredInputs") private Set requiredInputs; + /** + * Constructs a new {@code ResourceSpec} with the specified input and output properties and required fields. + * + * @param inputProperties a map of input property names to their specifications + * @param requiredInputs a set of required input property names + * @param properties a map of output property names to their specifications + * @param required a set of required output property names + */ public ResourceSpec( Map inputProperties, Set requiredInputs, @@ -29,14 +43,30 @@ public ResourceSpec( this.requiredInputs = new TreeSet<>(requiredInputs); } + /** + * Gets the map of input property names to their specifications for this resource. + * + * @return a map of input property names to {@link PropertySpec} instances + */ public Map getInputProperties() { return inputProperties; } + /** + * Gets the set of required input property names for this resource. + * + * @return a set of required input property names + */ public Set getRequiredInputs() { return requiredInputs; } + /** + * Compares this resource specification to another for equality. + * + * @param o the object to compare with + * @return {@code true} if the objects are equal, {@code false} otherwise + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -48,11 +78,21 @@ public boolean equals(Object o) { Objects.equals(requiredInputs, that.requiredInputs); } + /** + * Computes the hash code for this resource specification. + * + * @return the hash code value + */ @Override public int hashCode() { return Objects.hash(inputProperties, getProperties(), getRequired(), requiredInputs); } + /** + * Returns a string representation of this resource specification. + * + * @return a string describing the resource specification + */ @Override public String toString() { return "ResourceSpec{" + diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/TypeSpec.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/TypeSpec.java index 2f7bdf84795..35f8048cfab 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/TypeSpec.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/TypeSpec.java @@ -3,7 +3,14 @@ import com.google.gson.annotations.SerializedName; import java.util.Objects; +/** + * Represents a type specification in the provider schema. + * + * @see PropertySpec + * @see ComplexTypeSpec + */ public class TypeSpec { + @SerializedName("type") private String type; @@ -19,6 +26,15 @@ public class TypeSpec { @SerializedName("plain") private Boolean plain; + /** + * Constructs a new {@code TypeSpec} with the specified type, reference, plain flag, items, and additional properties. + * + * @param type the type name + * @param ref the reference to another type + * @param plain whether the type is plain + * @param items the type specification for array items + * @param additionalProperties the type specification for dictionary values= + */ public TypeSpec(String type, String ref, Boolean plain, TypeSpec items, TypeSpec additionalProperties) { this.type = type; this.ref = ref; @@ -30,50 +46,119 @@ public TypeSpec(String type, String ref, Boolean plain, TypeSpec items, TypeSpec this.additionalProperties = additionalProperties; } + /** + * Creates a {@code TypeSpec} for a built-in type. + * + * @param type the built-in type name + * @return a new {@code TypeSpec} instance for the specified built-in type + */ public static TypeSpec ofBuiltin(String type) { return ofBuiltin(type, null); } + /** + * Creates a {@code TypeSpec} for a built-in type with an optional plain flag. + * + * @param type the built-in type name + * @param plain whether the type is plain + * @return a new {@code TypeSpec} instance for the specified built-in type + */ public static TypeSpec ofBuiltin(String type, Boolean plain) { return new TypeSpec(type, null, plain, null, null); } + /** + * Creates a {@code TypeSpec} for a reference to another type. + * + * @param ref the reference to another type + * @return a new {@code TypeSpec} instance referencing the specified type + */ public static TypeSpec ofRef(String ref) { return ofRef(ref, null); } + /** + * Creates a {@code TypeSpec} for a reference to another type with an optional plain flag. + * + * @param ref the reference to another type + * @param plain whether the type is plain + * @return a new {@code TypeSpec} instance referencing the specified type + */ public static TypeSpec ofRef(String ref, Boolean plain) { return new TypeSpec(null, ref, plain, null, null); } + /** + * Creates a {@code TypeSpec} for an array type with the specified item type. + * + * @param items the type specification for array items + * @return a new {@code TypeSpec} instance representing an array of the specified item type + */ public static TypeSpec ofArray(TypeSpec items) { return new TypeSpec("array", null, null, items, null); } + /** + * Creates a {@code TypeSpec} for a dictionary type with the specified value type. + * + * @param additionalProperties the type specification for dictionary values + * @return a new {@code TypeSpec} instance representing a dictionary with the specified value type + */ public static TypeSpec ofDict(TypeSpec additionalProperties) { return new TypeSpec("object", null, null, null, additionalProperties); } + /** + * Gets the type name for this type specification. + * + * @return the type name + */ public String getType() { return type; } + /** + * Gets the type specification for array items, if this type is an array. + * + * @return the item type specification + */ public TypeSpec getItems() { return items; } + /** + * Gets the type specification for dictionary values + * + * @return the value type specification + */ public TypeSpec getAdditionalProperties() { return additionalProperties; } + /** + * Gets the reference to another type + * + * @return the reference string + */ public String getRef() { return ref; } + /** + * Gets whether this type is a plain type. + * + * @return {@code true} if this is a plain type otherwise {@code false} + */ public Boolean getPlain() { return plain; } + /** + * Compares this type specification to another for equality. + * + * @param o the object to compare with + * @return {@code true} if the objects are equal, {@code false} otherwise + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -86,11 +171,21 @@ public boolean equals(Object o) { Objects.equals(additionalProperties, that.additionalProperties); } + /** + * Computes the hash code for this type specification. + * + * @return the hash code value + */ @Override public int hashCode() { return Objects.hash(type, ref, plain, items, additionalProperties); } + /** + * Returns a string representation of this type specification. + * + * @return a string describing the type specification + */ @Override public String toString() { return "TypeSpec{" + diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/package-info.java new file mode 100644 index 00000000000..ee4731cc432 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/provider/internal/schema/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal schema definition utilities for providers. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.provider.internal.schema; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ComponentResource.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ComponentResource.java index 90bd8c0b46b..f03c1899bd7 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ComponentResource.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ComponentResource.java @@ -99,28 +99,64 @@ public ComponentResource(String type, String name, @Nullable ResourceArgs args, ); } + /** + * Registers the output properties for this component resource. + * + * @param outputs a map of output property names to their corresponding {@link Output} values; must not be null + * @see #registerOutputs(CompletableFuture) + * @see #registerOutputs(Output) + */ protected void registerOutputs(Map> outputs) { requireNonNull(outputs); registerOutputs(CompletableFuture.completedFuture(outputs)); } + /** + * Registers the output properties for this component resource asynchronously. + * + * @param outputs a {@link CompletableFuture} that will complete with a map of output property names to their {@link Output} values; must not be null + * @see #registerOutputs(Map) + * @see #registerOutputs(Output) + */ protected void registerOutputs(CompletableFuture>> outputs) { requireNonNull(outputs); registerOutputs(Output.of(outputs)); } + /** + * Registers the output properties for this component resource as an {@link Output}. + * + * @param outputs an {@link Output} containing a map of output property names to their {@link Output} values; must not be null + */ protected void registerOutputs(Output>> outputs) { requireNonNull(outputs); DeploymentInternal.getInstance().registerResourceOutputs(this, outputs); } + /** + * Internal helper class of {@link ComponentResource}. + * + * @see ComponentResource + * @see ResourceInternal + */ @InternalUse @ParametersAreNonnullByDefault public static class ComponentResourceInternal extends ResourceInternal { + /** + * Constructs a new internal accessor for the given {@link ComponentResource}. + * + * @param resource the {@link ComponentResource} instance to wrap + */ protected ComponentResourceInternal(ComponentResource resource) { super(resource); } + /** + * Creates a new {@link ComponentResourceInternal} accessor for the specified resource. + * + * @param r the {@link ComponentResource} to wrap + * @return a new {@link ComponentResourceInternal} instance for the given resource + */ public static ComponentResourceInternal from(ComponentResource r) { return new ComponentResourceInternal(r); } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResource.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResource.java index a0e60248d4d..00b342053b2 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResource.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResource.java @@ -118,17 +118,39 @@ public Output id() { return this.id; } + + /** + * Internal helper class for managing the internal state and lifecycle of a {@link CustomResource}. + * + * @see CustomResource + * @see ResourceInternal + */ @InternalUse @ParametersAreNonnullByDefault public static class CustomResourceInternal extends ResourceInternal { + /** + * The associated {@link CustomResource} instance whose internal state is managed. + */ private final CustomResource resource; + /** + * Constructs a new {@code CustomResourceInternal} for the specified {@link CustomResource}. + * + * @param resource the {@link CustomResource} to manage; must not be null + * @throws NullPointerException if {@code resource} is null + */ protected CustomResourceInternal(CustomResource resource) { super(resource); this.resource = requireNonNull(resource); } + /** + * Creates a new {@code CustomResourceInternal} instance for the given {@link CustomResource}. + * + * @param r the {@link CustomResource} to wrap; must not be null + * @return a new {@code CustomResourceInternal} instance managing {@code r} + */ public static CustomResourceInternal from(CustomResource r) { return new CustomResourceInternal(r); } @@ -136,7 +158,7 @@ public static CustomResourceInternal from(CustomResource r) { /** * More: {@link #id()} * - * @param id the the provider-assigned unique ID to set + * @param id the provider-assigned unique ID to set * @throws NullPointerException if id is null */ @InternalUse @@ -146,6 +168,13 @@ public void setId(Output id) { } } + /** + * Attempts to set the provider-assigned unique ID for the associated {@link CustomResource}. + * + * @param id the provider-assigned unique ID to set; must not be null + * @return {@code true} if the ID was set successfully; {@code false} if it was already set + * @throws NullPointerException if {@code id} is null + */ @InternalUse public boolean trySetId(Output id) { requireNonNull(id); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResourceOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResourceOptions.java index eb8c9c534b3..75483d06adb 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResourceOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/CustomResourceOptions.java @@ -57,6 +57,12 @@ public static Builder builder() { return new Builder(new CustomResourceOptions()); } + + /** + * Builder for {@link CustomResourceOptions}. + * + * @see CustomResourceOptions + */ public static final class Builder extends ResourceOptions.Builder { private Builder(CustomResourceOptions options) { @@ -66,6 +72,8 @@ private Builder(CustomResourceOptions options) { /** * When set to "true", indicates that this resource should be deleted before its * replacement is created when replacement is necessary. + * @param deleteBeforeReplace {@code true} to delete before replace; {@code false} to use default behavior + * @return this builder instance for method chaining */ public Builder deleteBeforeReplace(boolean deleteBeforeReplace) { options.deleteBeforeReplace = deleteBeforeReplace; @@ -78,12 +86,18 @@ public Builder deleteBeforeReplace(boolean deleteBeforeReplace) { * to your resource. It can be used to mark certain outputs as a secrets on a per-resource * basis. * + * @param additionalSecretOutputs one or more output names to treat as secrets + * @return this builder instance for method chaining */ public Builder additionalSecretOutputs(String... additionalSecretOutputs) { return this.additionalSecretOutputs(List.of(additionalSecretOutputs)); } /** + * Adds the names of outputs for this resource that should be treated as secrets. + * + * @param additionalSecretOutputs a list of output names to treat as secrets, or {@code null} for none + * @return this builder instance for method chaining * @see #additionalSecretOutputs(String...) */ public Builder additionalSecretOutputs(@Nullable List additionalSecretOutputs) { @@ -96,12 +110,18 @@ public Builder additionalSecretOutputs(@Nullable List additionalSecretOu * import its state from the cloud resource with the given ID.The inputs to the resource's * constructor must align with the resource's current state.Once a resource has been * imported, the import property must be removed from the resource's options. + * + * @param importId the provider-assigned unique ID of the resource to import, or {@code null} to disable import + * @return this builder instance for method chaining */ public Builder importId(@Nullable String importId) { options.importId = importId; return this; } + /** + * Builds a new {@link CustomResourceOptions} instance with the configured settings. + */ public CustomResourceOptions build() { return this.options; } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/InputArgs.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/InputArgs.java index af3f25d5895..918e96bc68f 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/InputArgs.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/InputArgs.java @@ -35,16 +35,36 @@ protected InputArgs() { protected abstract void validateMember(Class memberType, String fullName); + + /** + * Internal utility class of {@link InputArgs} instances. + * + * @see InputArgs + */ @InternalUse @ParametersAreNonnullByDefault public static final class InputArgsInternal { + /** + * The {@link InputArgs} instance. + */ private final InputArgs inputArgs; + /** + * Constructs a new internal utility for the given {@link InputArgs} instance. + * + * @param inputArgs the input arguments to manage; must not be null + */ private InputArgsInternal(InputArgs inputArgs) { this.inputArgs = requireNonNull(inputArgs); } + /** + * Creates a new {@link InputArgsInternal} instance from the given {@link InputArgs}. + * + * @param inputArgs the input arguments to wrap; must not be null + * @return a new internal utility instance managing the given input arguments + */ public static InputArgsInternal from(InputArgs inputArgs) { return new InputArgsInternal(inputArgs); } diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ProviderResource.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ProviderResource.java index a3e900a13d2..912aa7ae29f 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ProviderResource.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ProviderResource.java @@ -86,26 +86,58 @@ private CompletableFuture registrationIdAsync() { )); } + /** + * Internal implementation class for {@link ProviderResource} + * responsible for managing the lifecycle, registration, and state of provider resources within the Pulumi engine. + * + * @see ProviderResource + * @see CustomResourceInternal + * @see com.pulumi.resources.Resource + */ @InternalUse @ParametersAreNonnullByDefault public static final class ProviderResourceInternal extends CustomResourceInternal { + /** + * The associated {@link ProviderResource} instance that this internal class manages. + */ private final ProviderResource resource; + /** + * Constructs a new internal provider resource manager for the given {@link ProviderResource}. + * + * @param resource the provider resource to be managed; must not be null + */ private ProviderResourceInternal(ProviderResource resource) { super(resource); this.resource = requireNonNull(resource); } + /** + * Creates a new {@link ProviderResourceInternal} instance from the given {@link ProviderResource}. + * + * @param r the provider resource to wrap; must not be null + * @return a new internal provider resource instance managing the given provider + */ public static ProviderResourceInternal from(ProviderResource r) { return new ProviderResourceInternal(r); } + /** + * Retrieves the registration ID associated with the managed provider resource. + * + * @return a future that completes with the registration ID string + */ @InternalUse public CompletableFuture getRegistrationId() { return this.resource.registrationId; } + /** + * Gets the package name associated with the managed provider resource. + * + * @return the provider package name + */ @InternalUse public String getPackage() { return this.resource.aPackage; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resource.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resource.java index 7585ac1ca18..65c35f21b99 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resource.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resource.java @@ -314,20 +314,45 @@ private static ImmutableMap convertToProvidersMap(@Nul return result.build(); } + /** + * Internal utility for {@link Resource}. + * + * @see Resource + * @see ProviderResource + */ @InternalUse @ParametersAreNonnullByDefault public static class ResourceInternal { + /** + * The associated {@link Resource} instance that this internal class manages. + */ protected final Resource resource; + /** + * Constructs a new internal resource manager for the given {@link Resource}. + * + * @param resource the resource to be managed; must not be null + */ protected ResourceInternal(Resource resource) { this.resource = requireNonNull(resource); } + /** + * Creates a new {@link ResourceInternal} instance from the given {@link Resource}. + * + * @param r the resource to wrap; must not be null + * @return a new internal resource instance managing the given resource + */ public static ResourceInternal from(Resource r) { return new ResourceInternal(r); } + /** + * Returns whether the resource is remote. + * + * @return true if the resource is remote, false otherwise + */ @InternalUse public boolean getRemote() { return this.resource.remote; @@ -335,6 +360,8 @@ public boolean getRemote() { /** * The specified provider or provider determined from the parent for custom resources. + * + * @return an {@link Optional} containing the provider if set, or empty if not */ @InternalUse public Optional getProvider() { @@ -389,42 +416,96 @@ static public ProviderResource getProvider(Resource resource, String moduleMembe } } + /** + * Internal utility for lazily-initialized fields in a {@link Resource}. + */ @SuppressWarnings("OptionalUsedAsFieldOrParameterType") @InternalUse @ParametersAreNonnullByDefault public static class LazyFields { + + /** + * The lazily-initialized ID field for the resource, if present. + */ private final LazyField urn; + /** + * The lazily-initialized URN field for the resource. + */ private final Optional> id; + /** + * Constructs a new instance of {@link LazyFields} with the given URN and optional ID fields. + * + * @param urn the lazy URN field for the resource; must not be null + * @param id an optional lazy ID field for the resource; may be empty + */ protected LazyFields(LazyField urn, Optional> id) { this.urn = requireNonNull(urn); this.id = requireNonNull(id); } + /** + * Returns the lazy URN field for the resource. + * + * @return the lazy URN field + */ public LazyField urn() { return this.urn; } + /** + * Returns the optional lazy ID field for the resource. + * + * @return the optional lazy ID field + */ public Optional> id() { return this.id; } } + /** + * An interface for lazy fields in a {@link Resource}. + * + * @param the type of the field value + */ @InternalUse public interface LazyField { + /** + * Returns the underlying {@link CompletableFuture} for this field. + * + * @return the {@link CompletableFuture} representing the asynchronous value of this field + */ CompletableFuture> future(); + /** + * Completes this field with the given value, or throws if already completed. + * + * @param value the {@link Output} value to complete the field with + * @throws IllegalStateException if the field has already been completed + */ default void completeOrThrow(Output value) { if (!complete(value)) { throw new IllegalStateException("lazy field cannot be set twice, must be 'null' for 'set' to work"); } } + /** + * Attempts to complete this field with the given value. + * + * @param value the {@link Output} value to complete the field with + * @return {@code true} if the field was completed, {@code false} if it was already set + */ default boolean complete(Output value) { requireNonNull(value); return future().complete(value); } + /** + * Fails this field with the given throwable, completing the future exceptionally. + * + * @param throwable the exception to fail the field with + * @return {@code true} if the field was completed exceptionally, {@code false} if it was already set + */ default boolean fail(Throwable throwable) { requireNonNull(throwable); return complete(Output.of(CompletableFuture.failedFuture(throwable))); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ResourceOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ResourceOptions.java index dd820fdde88..93ca3dcacaf 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/ResourceOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/ResourceOptions.java @@ -78,15 +78,32 @@ protected ResourceOptions( this.pluginDownloadURL = pluginDownloadURL; } + + /** + * Abstract builder class for constructing and configuring {@link ResourceOptions} instances. + * @see ResourceOptions + */ protected static abstract class Builder> { + /** + * The options instance being configured by this builder. + */ protected final T options; + /** + * Constructs a new builder for the specified options instance. + * + * @param options the ResourceOptions instance to configure + */ protected Builder(T options) { this.options = options; } /** + * An optional existing ID to load, rather than create. + * + * @param id the Output-wrapped resource ID, or null to unset + * @return this builder for method chaining * @see #id(String) */ public B id(@Nullable Output id) { @@ -97,6 +114,9 @@ public B id(@Nullable Output id) { /** * An optional existing ID to load, rather than create. + * + * @param id the resource ID as a String, or null to unset + * @return this builder for method chaining */ public B id(@Nullable String id) { options.id = Output.ofNullable(id); @@ -106,6 +126,9 @@ public B id(@Nullable String id) { /** * An optional parent resource to which this resource belongs. + * + * @param parent the parent resource, or null if none + * @return this builder for method chaining */ public B parent(@Nullable Resource parent) { options.parent = parent; @@ -115,6 +138,9 @@ public B parent(@Nullable Resource parent) { /** * Optional additional explicit dependencies on other resources. + * + * @param dependsOn one or more resources this resource depends on + * @return this builder for method chaining */ public B dependsOn(Resource... dependsOn) { return this.dependsOn(List.of(dependsOn)); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resources.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resources.java index e7675dd4bb1..5aafd785206 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resources.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/Resources.java @@ -6,12 +6,30 @@ import java.util.ArrayList; import java.util.List; +/** + * Utility class providing helper methods for working with resource collections. + * + * @see Resource + */ public class Resources { + /** + * Private constructor to prevent instantiation of this utility class. + * + * @throws UnsupportedOperationException always thrown to prevent instantiation + */ private Resources() { throw new UnsupportedOperationException("static class"); } + /** + * Merges two nullable lists into a single list. + * + * @param original the original list, may be null + * @param additional the additional list to merge, may be null + * @param the type of elements in the lists + * @return a merged list containing all elements from both lists, or null if both are null + */ @Nullable protected static List mergeNullableList(@Nullable List original, @Nullable List additional) { if (original == null && additional == null) { @@ -30,7 +48,11 @@ protected static List mergeNullableList(@Nullable List original, @Null } /** - * @return a shallow copy of the {@code original} + * Returns a shallow copy of the given list, or null if the original is null. + * + * @param original the list to copy, may be null + * @param the type of elements in the list + * @return a shallow copy of the {@code original} list, or null if the original is null */ protected static List copyNullableList(@Nullable List original) { if (original == null) { @@ -39,6 +61,14 @@ protected static List copyNullableList(@Nullable List original) { return List.copyOf(original); } + /** + * Creates a copy of the given object that implements the {@link Copyable} interface. + * If the original object is null, returns null. + * + * @param original the object to copy, may be null + * @param the type of the object, must implement {@link Copyable} + * @return a copy of the original object, or null if the original is null + */ protected static > T copyNullable(@Nullable T original) { if (original == null) { return null; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/StackOptions.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/StackOptions.java index 313827ac476..d7bd99714c1 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/resources/StackOptions.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/StackOptions.java @@ -8,7 +8,7 @@ import static java.util.Objects.requireNonNull; /** - * @see StackOptions is a bag of optional settings that control a stack's behavior. + * {@link StackOptions} is a bag of optional settings that control a stack's behavior. */ @ParametersAreNonnullByDefault public class StackOptions { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/internal/package-info.java new file mode 100644 index 00000000000..9e3ab120c65 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal resource types for Pulumi. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.resources.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/resources/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/resources/package-info.java new file mode 100644 index 00000000000..f48c2484f8a --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/resources/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides core classes for defining and managing infrastructure resources. + */ +package com.pulumi.resources; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/serialization/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/serialization/internal/package-info.java new file mode 100644 index 00000000000..00ec8ac2bca --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/serialization/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Provides internal serialization and deserialization utilities for the SDK and engine. + *

+ * Note: This package is intended for internal use by the Pulumi Java SDK and is not designed for direct use by application developers. + */ +package com.pulumi.serialization.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/EmptyMocks.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/EmptyMocks.java index c32db632991..67ec880ab42 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/test/EmptyMocks.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/EmptyMocks.java @@ -4,8 +4,18 @@ import static java.lang.String.format; +/** + * Represents a {@link Mocks} implementation that throws for all resource mocks. + */ public class EmptyMocks implements Mocks { + /** + * Throws an exception indicating that no resource mocks are implemented. + * + * @param args Resource arguments. + * @return This method never returns normally. + * @throws IllegalArgumentException always thrown to indicate missing mocks. + */ @Override public CompletableFuture newResourceAsync(ResourceArgs args) { throw new IllegalArgumentException( diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockEngine.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockEngine.java index 0f924617d0d..091ad1f4537 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockEngine.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockEngine.java @@ -11,21 +11,49 @@ import java.util.concurrent.ConcurrentLinkedQueue; import java.util.concurrent.atomic.AtomicReference; +/** + * MockEngine is a test implementation of the {@link Engine} and {@link CountingLogger} interfaces for unit tests. + * + * @see com.pulumi.deployment.internal.Engine + * @see com.pulumi.deployment.internal.CountingLogger + */ public class MockEngine implements Engine, CountingLogger { + /** + * The URN of the root resource for the test deployment, managed atomically. + */ private final AtomicReference rootResourceUrn = new AtomicReference<>(null); + /** + * A thread-safe queue of error messages logged during the test execution. + */ private final Queue errors = new ConcurrentLinkedQueue<>(); + /** + * Returns the number of error messages logged by this engine. + * + * @return the count of logged errors + */ @Override public int getErrorCount() { return errors.size(); } + /** + * Checks if any error messages have been logged. + * + * @return true if errors have been logged, false otherwise + */ @Override public boolean hasLoggedErrors() { return !errors.isEmpty(); } + /** + * Logs a message asynchronously. If the message severity is ERROR, it is tracked in the error queue. + * + * @param request the log request containing the message and severity + * @return a completed future when logging is done + */ @Override public CompletableFuture logAsync(EngineOuterClass.LogRequest request) { if (request.getSeverity() == EngineOuterClass.LogSeverity.ERROR) { @@ -35,10 +63,22 @@ public CompletableFuture logAsync(EngineOuterClass.LogRequest request) { return CompletableFuture.completedFuture(null); } + /** + * Returns a collection of all error messages logged during the test. + * + * @return a collection of error messages + */ public Collection getErrors() { return errors; } + /** + * Sets the root resource URN for the test deployment. Throws if already set to a different value. + * + * @param request the set root resource request containing the URN + * @return a completed future with the set root resource response + * @throws IllegalStateException if the root resource is already set to a different URN + */ @Override public CompletableFuture setRootResourceAsync(EngineOuterClass.SetRootResourceRequest request) { if (rootResourceUrn.get() != null && !Objects.equals(rootResourceUrn.get(), request.getUrn())) { @@ -53,6 +93,13 @@ public CompletableFuture setRootResour return CompletableFuture.completedFuture(EngineOuterClass.SetRootResourceResponse.newBuilder().build()); } + /** + * Gets the root resource URN for the test deployment. + * + * @param request the get root resource request + * @return a completed future with the get root resource response containing the URN + * @throws IllegalStateException if the root resource has not been set + */ @Override public CompletableFuture getRootResourceAsync(EngineOuterClass.GetRootResourceRequest request) { if (rootResourceUrn.get() == null) { diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockMonitor.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockMonitor.java index d4975fd22f4..42714553c62 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockMonitor.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockMonitor.java @@ -38,16 +38,45 @@ import static com.pulumi.resources.internal.Stack.RootPulumiStackTypeName; + +/** + * MockMonitor is a test implementation of the {@link Monitor} interface for use with unit tests.. + * + * @see com.pulumi.test.Mocks + * @see com.pulumi.deployment.internal.Monitor + */ @InternalUse public class MockMonitor implements Monitor { + /** + * The user-provided mocks implementation used to simulate resource operations. + */ private final Mocks mocks; + /** + * Serializer for converting Java objects to protocol buffer structs. + */ private final Serializer serializer; + /** + * Deserializer for converting protocol buffer structs to Java objects. + */ private final Deserializer deserializer; + /** + * Map of URN to registered resource state, used to track resources created during the test. + */ private final Map> registeredResources; + /** + * List of all resources registered via this monitor during the test lifecycle. + */ public final List resources; + /** + * Constructs a new MockMonitor instance. + * + * @param mocks the {@link Mocks} implementation to use for simulating resource operations + * @param log the {@link Log} instance for logging serialization/deserialization events + * @throws NullPointerException if mocks is null + */ public MockMonitor(Mocks mocks, Log log) { this.mocks = Objects.requireNonNull(mocks); this.serializer = new Serializer(log); @@ -56,6 +85,12 @@ public MockMonitor(Mocks mocks, Log log) { this.resources = Collections.synchronizedList(new LinkedList<>()); } + /** + * Checks if a given feature is supported by this monitor implementation. + * + * @param request the feature support request + * @return a future containing the feature support response + */ @Override public CompletableFuture supportsFeatureAsync(SupportsFeatureRequest request) { var hasSupport = !"outputValues".equals(request.getId()); @@ -64,6 +99,13 @@ public CompletableFuture supportsFeatureAsync(SupportsF ); } + /** + * Invokes a provider function or retrieves a resource, delegating to the mocks implementation. + * + * @param request the invoke request + * @return a future containing the invoke response with serialized results + * @throws IllegalArgumentException if a requested resource URN is not found + */ @Override public CompletableFuture invokeAsync(pulumirpc.Resource.ResourceInvokeRequest request) { var args = deserializeToMap(request.getArgs()); @@ -85,6 +127,12 @@ public CompletableFuture invokeAsync(pulumirpc.Resource.Resource .thenApply(struct -> InvokeResponse.newBuilder().setReturn(struct).build()); } + /** + * Invokes a provider call, delegating to the mocks implementation. + * + * @param request the call request + * @return a future containing the call response with serialized results + */ @Override public CompletableFuture callAsync(ResourceCallRequest request) { // For now, we'll route both Invoke and Call through IMocks.CallAsync. @@ -98,6 +146,13 @@ public CompletableFuture callAsync(ResourceCallRequest request) { .thenApply(struct -> CallResponse.newBuilder().setReturn(struct).build()); } + /** + * Reads the state of an existing resource, simulating a resource read operation. + * + * @param resource the resource instance being read + * @param request the read resource request + * @return a future containing the read resource response with serialized state + */ @Override public CompletableFuture readResourceAsync(Resource resource, ReadResourceRequest request) { return ContextAwareCompletableFuture.wrap(mocks.newResourceAsync(new Mocks.ResourceArgs( @@ -135,6 +190,13 @@ public CompletableFuture readResourceAsync(Resource resour }); } + /** + * Registers a new resource, simulating resource creation and tracking its state. + * + * @param resource the resource instance being registered + * @param request the register resource request + * @return a future containing the register resource response with URN and serialized state + */ @Override public CompletableFuture registerResourceAsync(Resource resource, RegisterResourceRequest request) { this.resources.add(resource); @@ -187,11 +249,23 @@ public CompletableFuture registerResourceAsync(Resourc }); } + /** + * Registers the outputs of a resource. This is a no-op in the mock implementation. + * + * @param request the register resource outputs request + * @return a completed future + */ @Override public CompletableFuture registerResourceOutputsAsync(RegisterResourceOutputsRequest request) { return CompletableFuture.completedFuture(null); } + /** + * Deserializes a protocol buffer struct to an immutable map of arguments. + * + * @param args the struct to deserialize + * @return an immutable map of deserialized arguments + */ private ImmutableMap deserializeToMap(Struct args) { var builder = ImmutableMap.builder(); for (var entry : args.getFieldsMap().entrySet()) { @@ -205,6 +279,13 @@ private ImmutableMap deserializeToMap(Struct args) { return builder.build(); } + /** + * Serializes an object to a protocol buffer struct asynchronously. + * + * @param o the object to serialize + * @return a future containing the serialized struct + * @throws IllegalArgumentException if the input is a CompletableFuture + */ private CompletableFuture serializeToStruct(Object o) { if (o instanceof CompletableFuture) { throw new IllegalArgumentException("Unexpected CompletableFuture"); @@ -212,6 +293,13 @@ private CompletableFuture serializeToStruct(Object o) { return serializeToMap(o).thenApply(Serializer::createStruct); } + /** + * Serializes an object to an immutable map asynchronously. + * + * @param o the object to serialize + * @return a future containing the serialized immutable map + * @throws UnsupportedOperationException if the serialization result is not a map + */ private CompletableFuture> serializeToMap(Object o) { if (o instanceof Map) { o = ImmutableMap.copyOf((Map) o); // defensive copy @@ -235,6 +323,12 @@ private CompletableFuture> serializeToMap(Object o) ); } + /** + * Registers a provider package. This is a stub implementation for testing. + * + * @param request the register package request + * @return a future containing the register package response with a mock reference + */ @Override public CompletableFuture registerPackageAsync(RegisterPackageRequest request) { return CompletableFuture.completedFuture(RegisterPackageResponse.newBuilder() diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockRunner.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockRunner.java index 8306c7becb0..8556e2f9043 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockRunner.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/MockRunner.java @@ -5,6 +5,10 @@ import java.util.concurrent.CompletableFuture; import java.util.function.Supplier; +/** + * A mock implementation of the {@link Runner} interface for use in testing scenarios. + * @see com.pulumi.deployment.internal.Runner + */ public class MockRunner implements Runner { @Override diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/PulumiTestInternal.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/PulumiTestInternal.java index 17a59e023c0..7b75b73f824 100644 --- a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/PulumiTestInternal.java +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/PulumiTestInternal.java @@ -164,28 +164,62 @@ public static OutputData extractOutputData(Output output) { return Internal.of(output).getDataAsync().join(); } + /** + * Internal implementation of the {@link com.pulumi.test.PulumiTest.API} interface for configuring and executing tests. + */ @InternalUse public static final class APIInternal implements PulumiTest.API { private final Builder builder = new Builder(); + /** + * Sets the {@link TestOptions} to be used for the test. + * + * @param options the test options to configure the test environment + * @return this API instance for method chaining + * @see com.pulumi.test.TestOptions + */ @Override public PulumiTest.API withOptions(TestOptions options) { this.builder.options(options); return this; } + /** + * Sets the {@link Mocks} implementation to be used for the test. + * + * @param mocks the mocks to simulate Pulumi engine and resource provider behavior + * @return this API instance for method chaining + * @see com.pulumi.test.Mocks + */ @Override public PulumiTest.API withMocks(Mocks mocks) { this.builder.mocks(mocks); return this; } + /** + * Executes the Pulumi stack test synchronously using the configured options and mocks. + * + * @param stack a {@link Consumer} that receives the Pulumi {@link Context} for test logic + * @return a {@link TestResult} containing the outcome of the test execution + * @see com.pulumi.Context + * @see com.pulumi.test.TestResult + */ @Override public TestResult runTest(Consumer stack) { return builder.build().runTest(stack); } + /** + * Executes the Pulumi stack test asynchronously using the configured options and mocks. + * + * @param stack a {@link Consumer} that receives the Pulumi {@link Context} for test logic + * @return a {@link CompletableFuture} that completes with the {@link TestResult} of the test execution + * @see com.pulumi.Context + * @see com.pulumi.test.TestResult + * @see java.util.concurrent.CompletableFuture + */ @Override public CompletableFuture runTestAsync(Consumer stack) { return builder.build().runTestAsync(stack); diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/package-info.java new file mode 100644 index 00000000000..50526eaab23 --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Internal utilities for supporting test infrastructure and mocking. + *

+ * Note: This package is primarily for internal use and is not intended for direct use by end users. + */ +package com.pulumi.test.internal; diff --git a/sdk/java/pulumi/src/main/java/com/pulumi/test/package-info.java b/sdk/java/pulumi/src/main/java/com/pulumi/test/package-info.java new file mode 100644 index 00000000000..3f29bdd9f9c --- /dev/null +++ b/sdk/java/pulumi/src/main/java/com/pulumi/test/package-info.java @@ -0,0 +1,4 @@ +/** + * Provides utilities for testing Pulumi programs. + */ +package com.pulumi.test;