The profiler turns declarations in a Java codebase into a validated Runtime Conditions Profile. Your code calls the declaration functions of generated binding packages on its classpath. The profiler finds those packages, verifies their resources, and reads your source without compiling or running it.
It does for Java what the TypeScript profiler and the Python profiler do for their languages. The same declarations produce the same profile in every language.
Runtime Conditions is currently seeking adoption by an established parent project. The repositories in this organization are split for hands-on usability, review, demos, and implementation feedback. They are not intended to present Runtime Conditions as a standalone foundation or competing project.
- A JDK, 17 or newer, to run the profiler. A JRE is not enough, because the profiler uses the JDK's parser (the jdk.compiler module) to read your source, and says so when it is missing. A runtime made with jlink that includes jdk.compiler also works: java.base, java.desktop, java.sql and jdk.compiler are all it needs.
- Generated Java binding packages for the extensions your code declares against, on the classpath.
They are built by the
Java binding emitter
in
runtimeconditions/extensions.
Use the API of the binding packages. Every argument of a declaration is a generated type, built with
new:
import io.runtimeconditions.bindings.commonintegrations.Bindings;
import io.runtimeconditions.bindings.commonintegrations.KeyValue;
import io.runtimeconditions.bindings.commonintegrations.KeyValueEngine;
import io.runtimeconditions.bindings.envconfiguration.KeyValueConfiguration;
import io.runtimeconditions.bindings.envconfiguration.KeyValueConfigurationEnv;
import io.runtimeconditions.bindings.envconfiguration.KeyValueConfigurationEnvItem;
import io.runtimeconditions.bindings.envconfiguration.KeyValueConfigurationEnvItemProperty;
import java.util.List;
final class Sessions {
static final Object CACHE = Bindings.cache(
new KeyValue(KeyValueEngine.REDIS),
new KeyValueConfiguration(
null,
new KeyValueConfigurationEnv(List.of(
new KeyValueConfigurationEnvItem("REDIS_URL", KeyValueConfigurationEnvItemProperty.URL, null, true)))));
}The generated types are records, enums, and sealed interfaces. A record's constructor takes its
fields in order, and null leaves an optional field out.
The profiler must be able to determine each value statically. It follows:
- string, number, boolean, and
nullliterals, and+between them; finalfields,finallocals, and interface constants, in the same class or another one, by simple name, qualified name, or static import;- enum constants such as
Method.GET; List.of,Arrays.asList,Collections.emptyList,Map.of, andMap.ofEntries;- union variants such as
new RequestBodySchema.Variant2(...).
A value it cannot determine, such as a method call, a parameter, or a field that is not final, fails
with the file, line, and column. It never produces a partial condition. Sources under src/test,
build output (target, build, out), hidden directories, and symbolic links are not read.
The profiler is a jar, so it runs on whichever JDK starts it. The rc-profiler-java launcher in
distribution/ starts it on the JDK a Java developer would expect, the first of:
- RC_JAVA_HOME, to use a different JDK from your build's own;
- JAVA_HOME, which Maven, Gradle, IDEs, SDKMAN and CI setup steps set;
- the runtime bundled next to the jar, in a system package;
- java on PATH.
A variable that is set but names no JDK is an error; the launcher never falls back past it. The JDK must be
17 or newer, and at least as new as the Java your code uses, because it supplies the parser. Set
RC_JAVA_PROFILER_JAR to run a jar by its path. The launcher is a POSIX shell script; on Windows run
java -jar directly.
java -jar runtimeconditions-java-profiler.jar profile generate \
--project path/to/service \
--classpath path/to/common-integrations.jar:path/to/env-configuration.jar \
--name sessions \
--workload-uri https://services.example.com/sessions \
--workload-version 1.0.0 \
--out runtimeconditions.profile.yamlWithout --out the profile is printed. A failed run writes nothing and leaves an existing output file
alone. --json turns a failure into one JSON object on standard error.
--classpath takes jars or directories separated by : (; on Windows). Instead, or as well,
--resolve-build-classpath asks the project's own build tool for its runtime classpath: Maven
(./mvnw or mvn) or Gradle (./gradlew or gradle). That runs your build, so it is only done
when you ask for it. The profiler itself never runs your code or the binding packages.
profile verify-bindings verifies the packages and lists the ones your project imports, with the
extensions they depend on marked as dependencies:
java -jar runtimeconditions-java-profiler.jar profile verify-bindings --project path/to/service --classpath ...Before it reads any source, the profiler checks every binding package on the classpath:
- the package carries
runtimeconditions/runtimeconditions.bindings.yaml,runtimeconditions.binding-model.yaml,runtimeconditions.extension.yaml, and aruntimeconditions.file-manifest.yamlthat lists the SHA-256 of each; the digests must match; - the manifest and the model match their schemas, the model was generated against the core profile schema this profiler bundles, and the manifest, model, and extension definition agree on the model digest, the root extension, and its identity;
- the package is for Java, and when it is a jar its Maven coordinates match the manifest;
- every extension a package was generated against has a binding package on the classpath, with the same digest.
The finished profile is then validated against the core profile schema and every extension schema in the dependency closure. Invalid output is never written.
mvn verifytarget/runtimeconditions-java-profiler-<version>.jar is a runnable jar with its dependencies.
The profiler knows no extension by name: it reads the declaration functions, types, and schemas from
the packages' manifests and models. Its tests are general in the same way. They use the conformance
cases of runtimeconditions/extensions, small made-up extensions that each exercise one shape of the
binding model: an owned kind and interface, an additive field, transitive dependencies, a recursive type, a
union, collections and maps, values scoped to an interface type, Unicode names, and an extension that is
only a dependency. scripts/build-test-packages.py builds the packages in src/test/resources/packages
from them with the normalizer and the Java binding emitter. They have the layout that
ci/generate-java.py
generates: the three resources and a file manifest in the runtimeconditions directory.
Each workload under src/test/resources/workloads declares against one case, and the profile it produces
is compared with the reviewed one in src/test/resources/expected.