Package name.jurgenei.gradle.xml

Class AbstractXmlTransformTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
org.gradle.api.internal.ConventionTask
org.gradle.api.tasks.SourceTask
name.jurgenei.gradle.xml.AbstractXmlTransformTask
All Implemented Interfaces:
Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.IConventionAware, org.gradle.api.internal.TaskInternal, org.gradle.api.Named, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.api.tasks.util.PatternFilterable, org.gradle.util.Configurable<org.gradle.api.Task>
Direct Known Subclasses:
XQueryTask, XsltTask, XSpecCompileTask, XSpecTask
@DisableCachingByDefault(because="Uses external transform engines and file trees") public abstract class AbstractXmlTransformTask extends org.gradle.api.tasks.SourceTask
Shared base task for Saxon-backed file-to-file XML transformations.

This task provides Gradle-style input selection via SourceTask.source(Object...) or fileset(Object, Action), output mapping, parameter passing, and optional parallel processing with virtual-thread workers.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    AbstractXmlTransformTask.JsonMode
    JSON routing mode for .json files.

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields inherited from interface org.gradle.api.Task

    TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractXmlTransformTask()
    Creates a task with default conventions.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    fileset(Object baseDir, org.gradle.api.Action<? super org.gradle.api.file.ConfigurableFileTree> configureAction)
    Adds an Ant-like fileset rooted at baseDir.
    abstract org.gradle.api.provider.Property<Boolean>
    getFailOnError()
    Controls whether a task failure should fail the build when a single file transform fails.
    abstract org.gradle.api.file.RegularFileProperty
    getInputFile()
    Optional explicit single input file.
    abstract org.gradle.api.provider.Property<String>
    getJsonMode()
    Optional JSON mode controlling how .json input/output is routed.
    org.gradle.api.provider.Property<String>
    getMode()
    Backward-compatible alias for getOutputMode().
    abstract org.gradle.api.file.DirectoryProperty
    getOutputDir()
    Destination root directory for transformed files.
    abstract org.gradle.api.provider.Property<String>
    getOutputExtension()
    Output file extension used when mapping each input file to an output file.
    abstract org.gradle.api.file.RegularFileProperty
    getOutputFile()
    Optional explicit single output file.
    org.gradle.api.provider.Property<String>
    getOutputFormat()
    Canonical output-format alias for getXirFormat().
    abstract org.gradle.api.provider.Property<String>
    getOutputMethod()
    Optional explicit serializer output method used by Saxon.
    org.gradle.api.provider.Property<String>
    getOutputMode()
    Canonical output-mode alias for getJsonMode().
    abstract org.gradle.api.provider.MapProperty<String,String>
    getParams()
    Transform parameters exposed to the execution engine.
    org.gradle.api.file.FileTree
    getSource()
     
    abstract org.gradle.api.provider.Property<Integer>
    getWorkers()
    Number of worker threads used when processing multiple files.
    org.gradle.api.provider.Property<String>
    getXformat()
    Backward-compatible alias for getOutputFormat().
    abstract org.gradle.api.provider.Property<String>
    getXirFormat()
    Optional XIR output format used when writing .xir files.
    void
    input(Object path)
    Sets an explicit single input file (Ant-like in).
    protected boolean
    isJsonFile(File file)
    Checks whether file extension matches JSON input/output.
    protected boolean
    isStrictCanonicalJsonOutput(File outputFile)
    CANONICAL mode treats canonical JSON serialization failures as hard errors.
    protected boolean
    isXirFile(File file)
    Checks whether file extension matches S-expression input/output.
    void
    jsonMode(String mode)
    Sets JSON routing mode (Gradle DSL friendly).
    protected long
    latestDependencyTimestamp(File inputFile)
    Returns the newest timestamp of any file dependency that influences a transformation.
    void
    mode(String mode)
    Backward-compatible alias for outputMode(String).
    void
    output(Object path)
    Sets an explicit single output file (Ant-like out).
    void
    outputFormat(String format)
    Sets explicit S-expression output format using canonical DSL name.
    void
    outputMethod(String method)
    Sets an explicit serializer output method (Gradle DSL friendly).
    void
    outputMode(String mode)
    Sets JSON routing mode using canonical DSL name.
    void
    param(String name, Object value)
    Adds or overrides a transformation parameter.
    protected AbstractXmlTransformTask.JsonMode
    resolveJsonMode()
    Resolves JSON routing mode from explicit task setting.
    protected String
    resolveSerializerMethod(File outputFile)
    Resolves the serializer output method from explicit task setting or output extension.
    protected name.jurgenei.xir.XirSerializer.OutputFormat
    resolveXirOutputFormat()
    Resolves S-expression serializer format from explicit task setting.
    void
    setMode(String mode)
    Groovy/Kotlin assignment-style alias for mode(String).
    void
    setOutputFormat(String format)
    Groovy/Kotlin assignment-style alias for outputFormat(String).
    void
    setOutputMode(String mode)
    Groovy/Kotlin assignment-style alias for outputMode(String).
    void
    setXformat(String format)
    Groovy/Kotlin assignment-style alias for xformat(String).
    protected boolean
    shouldAttemptCanonicalJsonOutput(File outputFile)
    JSON output should attempt canonical hierarchical serialization.
    protected abstract void
    transform(File inputFile, File outputFile, Map<String,String> params)
    Executes one transformation from input file to output file.
    void
    transformAll()
    Executes transformations for all resolved source files.
    protected boolean
    useCanonicalJsonInput(File inputFile)
    AUTO and CANONICAL parse .json via canonical JSON reader.
    void
    xformat(String format)
    Backward-compatible alias for outputFormat(String).
    void
    xirFormat(String format)
    Sets explicit S-expression output format (Gradle DSL friendly).

    Methods inherited from class org.gradle.api.tasks.SourceTask

    exclude, exclude, exclude, exclude, getExcludes, getIncludes, getPatternSet, getPatternSetFactory, include, include, include, include, setExcludes, setIncludes, setSource, setSource, source

    Methods inherited from class org.gradle.api.internal.ConventionTask

    conventionMapping, conventionMapping, getConventionMapping

    Methods inherited from class org.gradle.api.DefaultTask

    compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService

    Methods inherited from class org.gradle.api.internal.AbstractTask

    acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getLoggingManager, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.gradle.api.Task

    doNotTrackState, notCompatibleWithConfigurationCache

  • Constructor Details

    • AbstractXmlTransformTask

      public AbstractXmlTransformTask()
      Creates a task with default conventions.

  • Method Details

    • getOutputDir

      @Optional @OutputDirectory public abstract org.gradle.api.file.DirectoryProperty getOutputDir()
      Destination root directory for transformed files.
      Returns:
      output directory property

    • getInputFile

      @Optional @InputFile @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getInputFile()
      Optional explicit single input file.

      When set together with getOutputFile(), the task runs in single-file mode and does not require getOutputDir() mapping.

      Returns:
      explicit input file property

    • getOutputFile

      @Optional @OutputFile public abstract org.gradle.api.file.RegularFileProperty getOutputFile()
      Optional explicit single output file.
      Returns:
      explicit output file property

    • getOutputExtension

      @Input public abstract org.gradle.api.provider.Property<String> getOutputExtension()
      Output file extension used when mapping each input file to an output file.
      Returns:
      extension property, defaults to .xml

    • getOutputMethod

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getOutputMethod()
      Optional explicit serializer output method used by Saxon.

      Supported values are xml, json, and text. If not set, the method is inferred from the destination file extension.

      Returns:
      output method property

    • getXirFormat

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getXirFormat()
      Optional XIR output format used when writing .xir files.

      Supported values are compact (default) and beautified.

      Returns:
      S-expression output format property

    • getOutputFormat

      @Internal public org.gradle.api.provider.Property<String> getOutputFormat()
      Canonical output-format alias for getXirFormat().
      Returns:
      S-expression output format property

    • getXformat

      @Internal public org.gradle.api.provider.Property<String> getXformat()
      Backward-compatible alias for getOutputFormat().
      Returns:
      S-expression output format property

    • getJsonMode

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getJsonMode()
      Optional JSON mode controlling how .json input/output is routed.

      Supported values are auto (default), native, and canonical.

      Returns:
      JSON routing mode property

    • getOutputMode

      @Internal public org.gradle.api.provider.Property<String> getOutputMode()
      Canonical output-mode alias for getJsonMode().
      Returns:
      JSON routing mode property

    • getMode

      @Internal public org.gradle.api.provider.Property<String> getMode()
      Backward-compatible alias for getOutputMode().
      Returns:
      JSON routing mode property

    • getParams

      @Input public abstract org.gradle.api.provider.MapProperty<String,String> getParams()
      Transform parameters exposed to the execution engine.
      Returns:
      map of parameter names to values

    • getWorkers

      @Input public abstract org.gradle.api.provider.Property<Integer> getWorkers()
      Number of worker threads used when processing multiple files.
      Returns:
      worker-count property, defaults to 1

    • getFailOnError

      @Input public abstract org.gradle.api.provider.Property<Boolean> getFailOnError()
      Controls whether a task failure should fail the build when a single file transform fails.
      Returns:
      fail-on-error property

    • param

      public void param(String name, Object value)
      Adds or overrides a transformation parameter.
      Parameters:
      name - parameter name, must not be null
      value - parameter value, converted to string

    • fileset

      public void fileset(Object baseDir, org.gradle.api.Action<? super org.gradle.api.file.ConfigurableFileTree> configureAction)
      Adds an Ant-like fileset rooted at baseDir.
      Parameters:
      baseDir - base directory object accepted by Project.fileTree
      configureAction - include/exclude configuration action

    • input

      public void input(Object path)
      Sets an explicit single input file (Ant-like in).
      Parameters:
      path - file notation supported by Project.file

    • output

      public void output(Object path)
      Sets an explicit single output file (Ant-like out).
      Parameters:
      path - file notation supported by Project.file

    • outputMethod

      public void outputMethod(String method)
      Sets an explicit serializer output method (Gradle DSL friendly).
      Parameters:
      method - one of xml, json, text

    • xirFormat

      public void xirFormat(String format)
      Sets explicit S-expression output format (Gradle DSL friendly).
      Parameters:
      format - one of compact or beautified

    • outputFormat

      public void outputFormat(String format)
      Sets explicit S-expression output format using canonical DSL name.
      Parameters:
      format - one of compact or beautified

    • setOutputFormat

      public void setOutputFormat(String format)
      Groovy/Kotlin assignment-style alias for outputFormat(String).
      Parameters:
      format - one of compact or beautified

    • xformat

      public void xformat(String format)
      Backward-compatible alias for outputFormat(String).
      Parameters:
      format - one of compact or beautified

    • setXformat

      public void setXformat(String format)
      Groovy/Kotlin assignment-style alias for xformat(String).
      Parameters:
      format - one of compact or beautified

    • jsonMode

      public void jsonMode(String mode)
      Sets JSON routing mode (Gradle DSL friendly).
      Parameters:
      mode - one of auto, native, or canonical

    • outputMode

      public void outputMode(String mode)
      Sets JSON routing mode using canonical DSL name.
      Parameters:
      mode - one of auto, native, or canonical

    • setOutputMode

      public void setOutputMode(String mode)
      Groovy/Kotlin assignment-style alias for outputMode(String).
      Parameters:
      mode - one of auto, native, or canonical

    • mode

      public void mode(String mode)
      Backward-compatible alias for outputMode(String).
      Parameters:
      mode - one of auto, native, or canonical

    • setMode

      public void setMode(String mode)
      Groovy/Kotlin assignment-style alias for mode(String).
      Parameters:
      mode - one of auto, native, or canonical

    • getSource

      @PathSensitive(RELATIVE) public org.gradle.api.file.FileTree getSource()
      Overrides:
      getSource in class org.gradle.api.tasks.SourceTask

    • transformAll

      public void transformAll()
      Executes transformations for all resolved source files.

      Files are processed deterministically and may run in parallel when workers > 1.

    • latestDependencyTimestamp

      protected long latestDependencyTimestamp(File inputFile)
      Returns the newest timestamp of any file dependency that influences a transformation.

      By default this is the source file timestamp. Subclasses should override to include additional inputs such as stylesheets or query files.

      Parameters:
      inputFile - source XML document
      Returns:
      newest dependency timestamp in epoch milliseconds

    • resolveSerializerMethod

      protected String resolveSerializerMethod(File outputFile)
      Resolves the serializer output method from explicit task setting or output extension.
      Parameters:
      outputFile - destination file
      Returns:
      serializer method to pass to Saxon

    • resolveXirOutputFormat

      protected name.jurgenei.xir.XirSerializer.OutputFormat resolveXirOutputFormat()
      Resolves S-expression serializer format from explicit task setting.
      Returns:
      serializer format to use for .xir and canonical .json output

    • resolveJsonMode

      protected AbstractXmlTransformTask.JsonMode resolveJsonMode()
      Resolves JSON routing mode from explicit task setting.
      Returns:
      JSON mode

    • isXirFile

      protected boolean isXirFile(File file)
      Checks whether file extension matches S-expression input/output.
      Parameters:
      file - candidate file
      Returns:
      true when file extension is .xir

    • isJsonFile

      protected boolean isJsonFile(File file)
      Checks whether file extension matches JSON input/output.
      Parameters:
      file - candidate file
      Returns:
      true when file extension is .json

    • useCanonicalJsonInput

      protected boolean useCanonicalJsonInput(File inputFile)
      AUTO and CANONICAL parse .json via canonical JSON reader.
      Parameters:
      inputFile - candidate source file
      Returns:
      true when task should parse input using canonical JSON mapping

    • shouldAttemptCanonicalJsonOutput

      protected boolean shouldAttemptCanonicalJsonOutput(File outputFile)
      JSON output should attempt canonical hierarchical serialization.

      CANONICAL mode always attempts canonical JSON. AUTO/NATIVE attempt canonical JSON when the resolved serializer method is json.

      Parameters:
      outputFile - candidate destination file
      Returns:
      true when task should try canonical JSON serializer before native fallback

    • isStrictCanonicalJsonOutput

      protected boolean isStrictCanonicalJsonOutput(File outputFile)
      CANONICAL mode treats canonical JSON serialization failures as hard errors.
      Parameters:
      outputFile - candidate destination file
      Returns:
      true when canonical JSON serialization failure must fail task

    • transform

      protected abstract void transform(File inputFile, File outputFile, Map<String,String> params) throws Exception
      Executes one transformation from input file to output file.
      Parameters:
      inputFile - source XML document
      outputFile - destination file
      params - immutable task parameter view
      Throws:
      Exception - any transform exception raised by the engine implementation