Interface BuildScanApi
-
public interface BuildScanApi
Allows to interact with the build scan feature of the Develocity Maven extension.- Since:
- 1.21
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
background(java.util.function.Consumer<? super BuildScanApi> action)
Executes the given action in a background thread, allowing the current Maven work to continue.void
buildFinished(java.util.function.Consumer<? super BuildResult> action)
Registers a callback that is invoked when the build has finished, but before this extension stops accepting to be called.void
buildScanPublished(java.util.function.Consumer<? super PublishedBuildScan> action)
Registers a callback that is invoked when a build scan has been published successfully.void
capture(java.util.function.Consumer<? super BuildScanCaptureSettings> action)
Allows configuring what data will be captured as part of the build scan.void
executeOnce(java.lang.String identifier, java.util.function.Consumer<? super BuildScanApi> action)
Executes the given action only once over the course of the Maven build execution.boolean
getAllowUntrustedServer()
Whether it is acceptable to communicate with a build scan server with an untrusted SSL certificate.BuildScanCaptureSettings
getCapture()
Allows configuring what data will be captured as part of the build scan.BuildScanDataObfuscation
getObfuscation()
Allows registering functions for obfuscating certain identifying information within build scans.BuildScanPublishing
getPublishing()
Retrieves the build scan publication settings.java.lang.String
getServer()
Returns the URL of the Develocity server to which the build scans are published.java.lang.String
getTermsOfUseAgree()
The agreement of the Gradle Terms of Use specified undersetTermsOfUseUrl(String)
.java.lang.String
getTermsOfUseUrl()
The location of the Gradle Terms of Use that are agreed to when creating a build scan.boolean
isUploadInBackground()
void
link(java.lang.String name, java.lang.String url)
Captures a named link for the current build.void
obfuscation(java.util.function.Consumer<? super BuildScanDataObfuscation> action)
Allows registering functions for obfuscating certain identifying information within build scans.void
publishing(java.util.function.Consumer<? super BuildScanPublishing> action)
Allows configuring whether a build scan should be published at the end of the build.void
setAllowUntrustedServer(boolean allow)
Specifies whether it is acceptable to communicate with a Develocity server using an untrusted SSL certificate.default void
setServer(java.lang.String url)
Sets the URL of the Develocity server to which the build scans are published.void
setServer(java.net.URI url)
Sets the URL of the Develocity server to which the build scans are published.void
setTermsOfUseAgree(java.lang.String agree)
Indicates whether the Gradle Terms of Use specified undersetTermsOfUseUrl(String)
are agreed to.void
setTermsOfUseUrl(java.lang.String termsOfUseUrl)
The location of the Gradle Terms of Use that are agreed to when creating a build scan.void
setUploadInBackground(boolean uploadInBackground)
Specifies whether to upload the build scan in background after the build has finished.void
tag(java.lang.String tag)
Captures a tag for the current build.void
value(java.lang.String name, java.lang.String value)
Captures a named value for the current build.
-
-
-
Method Detail
-
tag
void tag(java.lang.String tag)
Captures a tag for the current build. The tag is not required to be unique for a given build.- Parameters:
tag
- the name of the tag, must not benull
-
value
void value(java.lang.String name, @Nullable java.lang.String value)
Captures a named value for the current build. The name is not required to be unique for a given build.- Parameters:
name
- the name, must not benull
value
- the value ornull
-
link
void link(java.lang.String name, java.lang.String url)
Captures a named link for the current build. The name is not required to be unique for a given build.- Parameters:
name
- the name, must not benull
url
- the url, must not benull
, must be a valid http:, https: or mailto: URL
-
background
void background(java.util.function.Consumer<? super BuildScanApi> action)
Executes the given action in a background thread, allowing the current Maven work to continue.This method is useful for capturing values, tags and links that are expensive to compute. By capturing them in the background, Maven can continue doing other work, making your build faster.
For example, if you are capturing the Git commit ID as a custom value you should invoke Git in the background:
import org.eclipse.jgit.*; background(api -> { Git git = ... ObjectId objectId = git.getRepository().resolve("HEAD"); api.value("Git Commit ID", ObjectId.toString(objectId)); });
All background work will be completed before finishing the build and publishing the build scan.
Any errors that are thrown by the background action will be logged and captured in the build scan.
- Parameters:
action
- the action to execute in the background
-
buildFinished
void buildFinished(java.util.function.Consumer<? super BuildResult> action)
Registers a callback that is invoked when the build has finished, but before this extension stops accepting to be called.- Parameters:
action
- the action to execute when the build has finished
-
buildScanPublished
void buildScanPublished(java.util.function.Consumer<? super PublishedBuildScan> action)
Registers a callback that is invoked when a build scan has been published successfully.If
isUploadInBackground()
istrue
, the callback is invoked as early as possible, which is as soon as the Develocity server provides a build scan URL, and before the actual upload to the server. This means that if the URL is accessed right away, it might not be available yet, as the build scan is still being transmitted and processed by the server.- Parameters:
action
- the action to execute when the build scan has been published successfully
-
setTermsOfUseUrl
void setTermsOfUseUrl(java.lang.String termsOfUseUrl)
The location of the Gradle Terms of Use that are agreed to when creating a build scan.Configuration via the
develocity.scan.termsOfUse.url
system property will always take precedence.- Parameters:
termsOfUseUrl
- the location of the Gradle Terms of Use
-
getTermsOfUseUrl
@Nullable java.lang.String getTermsOfUseUrl()
The location of the Gradle Terms of Use that are agreed to when creating a build scan.- Returns:
- the location of the Gradle Terms of Use or
null
-
setTermsOfUseAgree
void setTermsOfUseAgree(java.lang.String agree)
Indicates whether the Gradle Terms of Use specified undersetTermsOfUseUrl(String)
are agreed to.Configuration via the
develocity.scan.termsOfUse.accept
system property will always take precedence.- Parameters:
agree
- true if agreeing to the Gradle Terms of Use, false otherwise
-
getTermsOfUseAgree
@Nullable java.lang.String getTermsOfUseAgree()
The agreement of the Gradle Terms of Use specified undersetTermsOfUseUrl(String)
.- Returns:
- the agreement of the Gradle Terms of Use or
null
-
setServer
default void setServer(@Nullable java.lang.String url)
Sets the URL of the Develocity server to which the build scans are published.- Parameters:
url
- the server URL ornull
-
setServer
void setServer(@Nullable java.net.URI url)
Sets the URL of the Develocity server to which the build scans are published.- Parameters:
url
- the server URL ornull
-
getServer
@Nullable java.lang.String getServer()
Returns the URL of the Develocity server to which the build scans are published.- Returns:
- the Develocity server or
null
-
setAllowUntrustedServer
void setAllowUntrustedServer(boolean allow)
Specifies whether it is acceptable to communicate with a Develocity server using an untrusted SSL certificate.The default (public) build scan server uses SSL certificates that are trusted by default by standard modern Java environments. If you are using a different build scan server via Develocity, it may use an untrusted certificate. This may be due to the use of an internally provisioned or self-signed certificate.
In such a scenario, you can either configure the build JVM environment to trust the certificate, or call this method with
true
to disable verification of the server's identity. Alternatively, you may disable SSL completely for Develocity installation but this is not recommended.Allowing communication with untrusted servers keeps data encrypted during transmission, but makes it easy for a man-in-the-middle to impersonate the intended server and capture data.
This value has no effect if a server is specified using the HTTP protocol (i.e. has SSL disabled).
- Parameters:
allow
- whether to allow communication with an HTTPS server with an untrusted certificate
-
getAllowUntrustedServer
boolean getAllowUntrustedServer()
Whether it is acceptable to communicate with a build scan server with an untrusted SSL certificate.- Returns:
true
it is acceptable to communicate with a build scan server with an untrusted SSL certificate
-
setUploadInBackground
void setUploadInBackground(boolean uploadInBackground)
Specifies whether to upload the build scan in background after the build has finished.Defaults to
true
.This allows the build to finish sooner, but can be problematic in build environments that terminate as soon as the build is finished as the upload may be terminated before it completes. Background uploading should be disabled for such environments.
This property may also be set in
develocity.xml
or via thedevelocity.scan.uploadInBackground
system property, which if set takes precedence over any value set by this method and the default. If this is set to any value other thantrue
, the background build scan upload will be disabled.This method cannot be called after the MavenSession has been started (i.e. after the
ExecutionEvent.Type.SessionStarted
event has been received). Doing so will produce a build time error.- Parameters:
uploadInBackground
- whether to upload the build scan in background
-
isUploadInBackground
boolean isUploadInBackground()
- Returns:
- whether to upload build scan in background
-
executeOnce
void executeOnce(java.lang.String identifier, java.util.function.Consumer<? super BuildScanApi> action)
Executes the given action only once over the course of the Maven build execution.The identifier is used to uniquely identify a given action. Calling this API a second time with the same identifier will not run the action again.
Any errors that are thrown by the action will be logged and captured in the build scan. In case of a failure while executing the action for a given identifier, no other action will be executed for the same identifier.
- Parameters:
identifier
- a unique identifieraction
- the action to execute only once
-
getObfuscation
BuildScanDataObfuscation getObfuscation()
Allows registering functions for obfuscating certain identifying information within build scans.- Returns:
- the register of obfuscation functions
-
obfuscation
void obfuscation(java.util.function.Consumer<? super BuildScanDataObfuscation> action)
Allows registering functions for obfuscating certain identifying information within build scans.- Parameters:
action
- a function to be applied to the register of obfuscation functions
-
getCapture
BuildScanCaptureSettings getCapture()
Allows configuring what data will be captured as part of the build scan.- Returns:
- the capture settings
-
capture
void capture(java.util.function.Consumer<? super BuildScanCaptureSettings> action)
Allows configuring what data will be captured as part of the build scan.- Parameters:
action
- a function to be applied to the capture settings
-
getPublishing
BuildScanPublishing getPublishing()
Retrieves the build scan publication settings.- Returns:
- the publishing settings
-
publishing
void publishing(java.util.function.Consumer<? super BuildScanPublishing> action)
Allows configuring whether a build scan should be published at the end of the build.- Parameters:
action
- a function to be applied to the publishing settings
-
-