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
@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.
    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.
    abstract org.gradle.api.provider.Property<String>
    getOutputMethod()
    Optional explicit serializer output method used by Saxon.
    abstract org.gradle.api.provider.MapProperty<String,String>
    getParams()
    Transform parameters exposed to the execution engine.
    abstract org.gradle.api.provider.Property<String>
    getSexprFormat()
    Optional S-expression output format used when writing .sexpr files.
    org.gradle.api.file.FileTree
    getSource()
     
    abstract org.gradle.api.provider.Property<Integer>
    getWorkers()
    Number of worker threads used when processing multiple 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
    isSexprFile(File file)
    Checks whether file extension matches S-expression input/output.
    protected boolean
    isStrictCanonicalJsonOutput(File outputFile)
    CANONICAL mode treats canonical JSON serialization failures as hard errors.
    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
    output(Object path)
    Sets an explicit single output file (Ant-like out).
    void
    outputMethod(String method)
    Sets an explicit serializer output method (Gradle DSL friendly).
    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.xml.sexpr.SExpressionSerializer.OutputFormat
    resolveSexprOutputFormat()
    Resolves S-expression serializer format from explicit task setting.
    void
    sexprFormat(String format)
    Sets explicit S-expression output format (Gradle DSL friendly).
    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.

    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, 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

    • getSexprFormat

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getSexprFormat()
      Optional S-expression output format used when writing .sexpr files.

      Supported values are compact (default) and beautified.

      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

    • 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

    • sexprFormat

      public void sexprFormat(String format)
      Sets explicit S-expression output format (Gradle DSL friendly).
      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

    • 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

    • resolveSexprOutputFormat

      protected name.jurgenei.xml.sexpr.SExpressionSerializer.OutputFormat resolveSexprOutputFormat()
      Resolves S-expression serializer format from explicit task setting.
      Returns:
      serializer format to use for .sexpr and canonical .json output

    • resolveJsonMode

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

    • isSexprFile

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

    • 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