GSaha567/seq_level_training_data

1text,length,is_long_context,metric_val,label_metric2"// Copyright 2018 the original author or authors.3//4// Licensed under the Apache License, Version 2.0 (the ""License"");5// you may not use this file except in compliance with the License.6// You may obtain a copy of the License at7//8//      http://www.apache.org/licenses/LICENSE-2.09//10// Unless required by applicable law or agreed to in writing, software11// distributed under the License is distributed on an ""AS IS"" BASIS,12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.13// See the License for the specific language governing permissions and14// limitations under the License.15 16:kotlin-reference: https://kotlinlang.org/docs/reference/17:kotlin-tutorials: https://kotlinlang.org/tutorials/18:kotlin-dsl-samples: https://github.com/gradle/kotlin-dsl-samples/tree/master/samples19:gradle-issues: https://github.com/gradle/gradle/issues/20:plugin-portal: https://plugins.gradle.org/21 22[[kotlin_dsl]]23= Gradle Kotlin DSL Primer24 25Gradle's Kotlin DSL provides an alternative syntax to the traditional Groovy DSL with an enhanced editing experience in supported IDEs, with superior content assist, refactoring, documentation, and more.26This chapter provides details of the main Kotlin DSL constructs and how to use it to interact with the Gradle API.27 28[TIP]29====30If you are interested in migrating an existing Gradle build to the Kotlin DSL, please also check out the dedicated <<migrating_from_groovy_to_kotlin_dsl.adoc#,migration section>>.31====32 33 34[[kotdsl:prerequisites]]35== Prerequisites36 37* The embedded Kotlin compiler is known to work on Linux, macOS, Windows, Cygwin, FreeBSD and Solaris on x86-64 architectures.38* Knowledge of Kotlin syntax and basic language features is very helpful. The link:{kotlin-reference}[Kotlin reference documentation] and link:https://kotlinlang.org/docs/tutorials/koans.html[Kotlin Koans] will help you to learn the basics.39* Use of the <<plugins#sec:plugins_block,plugins {}>> block to declare Gradle plugins significantly improves the editing experience and is highly recommended.40 41[[sec:ide_support]]42== IDE support43 44The Kotlin DSL is fully supported by IntelliJ IDEA and Android Studio. Other IDEs do not yet provide helpful tools for editing Kotlin DSL files, but you can still import Kotlin-DSL-based builds and work with them as usual.45 46.IDE support matrix47[cols="">.^,^.^,^.^,^.^"",frame=none,grid=rows,options=""header""]48|===49||Build import|Syntax highlighting ^1^|Semantic editor ^2^50 51|IntelliJ IDEA52|[.green]#*✓*#53|[.green]#*✓*#54|[.green]#*✓*#55 56|Android Studio57|[.green]#*✓*#58|[.green]#*✓*#59|[.green]#*✓*#60 61|Eclipse IDE62|[.green]#*✓*#63|[.green]#*✓*#64|[.red]#✖#65 66|CLion67|[.green]#*✓*#68|[.green]#*✓*#69|[.red]#✖#70 71|Apache NetBeans72|[.green]#*✓*#73|[.green]#*✓*#74|[.red]#✖#75 76|Visual Studio Code ^(LSP)^77|[.green]#*✓*#78|[.green]#*✓*#79|[.red]#✖#80 81|Visual Studio82|[.green]#*✓*#83|[.red]#✖#84|[.red]#✖#85 86|===87 88[%hardbreaks]89^1^ ^Kotlin^ ^syntax^ ^highlighting^ ^in^ ^Gradle^ ^Kotlin^ ^DSL^ ^scripts^90^2^ ^code^ ^completion,^ ^navigation^ ^to^ ^sources,^ ^documentation,^ ^refactorings^ ^etc...^ ^in^ ^Gradle^ ^Kotlin^ ^DSL^ ^scripts^91 92As mentioned in the limitations, you must link:https://www.jetbrains.com/help/idea/gradle.html#gradle_import[import your project from the Gradle model] to get content-assist and refactoring tools for Kotlin DSL scripts in IntelliJ IDEA.93 94In addition, IntelliJ IDEA and Android Studio might spawn up to 3 Gradle daemons when editing Gradle scripts — one for each type of script: build scripts, settings files and initialization scripts.95Builds with slow configuration time might affect the IDE responsiveness, so please check out the <<performance.adoc#,performance section>> to help resolve such issues.96 97=== Automatic build import vs. automatic reloading of script dependencies98 99Both IntelliJ IDEA and Android Studio — which is derived from IntelliJ IDEA — will detect when you make changes to your build logic and offer two suggestions:100 101 1. Import the whole build again102+103image::intellij-build-import-popup.png[IntelliJ IDEA, width=300]104+105image::android-studio-build-sync-popup.png[IntelliJ IDEA]106 2. Reload script dependencies when editing a build script107+108image::intellij-script-dependencies-reload.png[Reload script dependencies]109 110We recommend that you _disable automatic build import_, but _enable automatic reloading of script dependencies_.111That way you get early feedback while editing Gradle scripts and control over when the whole build setup gets synchronized with your IDE.112 113=== Troubleshooting114 115The IDE support is provided by two components:116 117* The Kotlin Plugin used by IntelliJ IDEA/Android Studio118* Gradle119 120The level of support varies based on the versions of each.121 122If you run into trouble, the first thing you should try is running `./gradlew tasks` from the command line to see whether your issue is limited to the IDE. If you encounter the same problem from the command line, then the issue is with the build rather than the IDE integration.123 124If you can run the build successfully from the command line but your script editor is complaining, then you should try restarting your IDE and invalidating its caches.125 126If the above doesn't work and you suspect an issue with the Kotlin DSL script editor, you can:127 128* Run `./gradle tasks` to get more details129* Check the logs in one of these locations:130** `$HOME/Library/Logs/gradle-kotlin-dsl` on Mac OS X131** `$HOME/.gradle-kotlin-dsl/log` on Linux132** `$HOME/AppData/Local/gradle-kotlin-dsl/log` on Windows133* Open an issue on the link:{gradle-issues}[Gradle issue tracker], including as much detail as you can.134 135From version 5.1 onwards, the log directory is cleaned up automatically.136It is checked periodically (at most every 24 hours) and log files are deleted if they haven’t been used for 7 days.137 138If the above isn't enough to pinpoint the problem, you can enable the `org.gradle.kotlin.dsl.logging.tapi` system property in your IDE. This will cause the Gradle Daemon to log extra information in its log file located in `$HOME/.gradle/daemon`. In IntelliJ IDEA this can be done by opening `Help > Edit Custom VM Options...` and adding `-Dorg.gradle.kotlin.dsl.logging.tapi=true`.139 140For IDE problems outside of the Kotlin DSL script editor, please open issues in the corresponding IDE's issue tracker:141 142* link:[JetBrains's IDEA issue tracker],143* link:[Google's Android Studio issue tracker].144 145Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the link:{gradle-issues}[Gradle issue tracker].146 147 148[[sec:scripts]]149== Kotlin DSL scripts150 151Just like the Groovy-based equivalent, the Kotlin DSL is implemented on top of Gradle's Java API.152Everything you can read in a Kotlin DSL script is Kotlin code compiled and executed by Gradle.153Many of the objects, functions and properties you use in your build scripts come from the Gradle API and the APIs of the applied plugins.154 155=== Script file names156 157[NOTE]158====159Groovy DSL script files use the `.gradle` file name extension.160 161Kotlin DSL script files use the `.gradle.kts` file name extension.162====163 164To activate the Kotlin DSL, simply use the `.gradle.kts` extension for your build scripts in place of `.gradle`. That also applies to the <<build_lifecycle#sec:settings_file,settings file>> — for example `settings.gradle.kts` — and <<init_scripts#init_scripts,initialization scripts>>.165 166Note that you can mix Groovy DSL build scripts with Kotlin DSL ones, i.e. a Kotlin DSL build script can apply a Groovy DSL one and each project in a multi-project build can use either one.167 168We recommend that you apply the following conventions to get better IDE support:169 170* Name settings scripts (or any script that is backed by a Gradle `Settings` object) according to the pattern `*.settings.gradle.kts` — this includes script plugins that are applied from settings scripts171* Name <<init_scripts#init_scripts,initialization scripts>> according to the pattern `*.init.gradle.kts` or simply `init.gradle.kts`.172 173This is so that the IDE knows what type of object ""backs"" the script, be it link:{groovyDslPath}/org.gradle.api.Project.html[Project], link:{groovyDslPath}/org.gradle.api.initialization.Settings.html[Settings] or link:{groovyDslPath}/org.gradle.api.invocation.Gradle.html[Gradle].174 175[[sec:implicit_imports]]176=== Implicit imports177 178All Kotlin DSL build scripts have implicit imports consisting of:179 180* The <<writing_build_scripts#script-default-imports,default Gradle API imports>>181* The Kotlin DSL API, which is all types within the `org.gradle.kotlin.dsl` and `org.gradle.kotlin.dsl.plugins.dsl` packages currently182 183[CAUTION]184.Avoid using internal Kotlin DSL APIs185====186Use of internal Kotlin DSL APIs in plugins and build scripts has the potential to break builds when either Gradle or plugins change.187The link:{kotlinDslPath}/[Kotlin DSL API] extends the <<authoring_maintainable_build_scripts#sec:avoiding_gradle_internal_apis,Gradle public API>> with the types listed in the https://gradle.github.io/kotlin-dsl-docs/api/[corresponding API docs] that are in the `org.gradle.kotlin.dsl` or `org.gradle.kotlin.dsl.plugins.dsl` packages (but not subpackages of those).188====189 190 191[[sec:configuring_plugins]]192[[type-safe-accessors]]193== Type-safe model accessors194 195The Groovy DSL allows you to reference many elements of the build model by name, even when they are defined at runtime. Think named configurations, named source sets, and so on. For example, you can get hold of the `implementation` configuration via `configurations.implementation`.196 197The Kotlin DSL replaces such dynamic resolution with type-safe model accessors that work with model elements contributed by plugins.198 199[[kotdsl:accessor_applicability]]200=== Understanding when type-safe model accessors are available201 202The Kotlin DSL currently supports type-safe model accessors for any of the following that are contributed by plugins:203 204* Dependency and artifact configurations (such as `implementation` and `runtimeOnly` contributed by the Java Plugin)205* Project extensions and conventions (such as `sourceSets`)206* Elements in the `tasks` and `configurations` containers207* Elements in <<kotdsl:containers,project-extension containers>> (for example the source sets contributed by the Java Plugin that are added to the `sourceSets` container)208* Extensions on each of the above209 210[IMPORTANT]211====212Only the main project build scripts and precompiled project script plugins have type-safe model accessors.213Initialization scripts, settings scripts, script plugins do not.214These limitations will be removed in a future Gradle release.215====216 217The set of type-safe model accessors available is calculated right before evaluating the script body, immediately after the `plugins {}` block.218Any model elements contributed after that point do not work with type-safe model accessors.219For example, this includes any configurations you might define in your own build script.220However, this approach does mean that you can use type-safe accessors for any model elements that are contributed by plugins that are _applied by parent projects_.221 222The following project build script demonstrates how you can access various configurations, extensions and other elements using type-safe accessors:223 224.Using type-safe model accessors225====226include::sample[dir=""snippets/kotlinDsl/accessors/kotlin"",files=""build.gradle.kts[tags=accessors]""]227====228<1> Uses type-safe accessors for the `api`, `implementation` and `testImplementation` dependency configurations contributed by the <<java_library_plugin#java_library_plugin,Java Library Plugin>>229<2> Uses an accessor to configure the `sourceSets` project extension230<3> Uses an accessor to configure the `main` source set231<4> Uses an accessor to configure the `java` source for the `main` source set232<5> Uses an accessor to configure the `test` task233 234[TIP]235====236Your IDE knows about the type-safe accessors, so it will include them in its suggestions.237This will happen both at the top level of your build scripts — most plugin extensions are added to the `Project` object — and within the blocks that configure an extension.238====239 240Note that accessors for elements of containers such as `configurations`, `tasks` and `sourceSets` leverage Gradle's <<lazy_configuration#lazy_configuration,configuration avoidance APIs>>.241For example, on `tasks` they are of type `TaskProvider<T>` and provide a lazy reference and lazy configuration of the underlying task.242Here are some examples that illustrate the situations in which configuration avoidance applies:243 244[source,kotlin]245----246tasks.test {247    // lazy configuration248}249 250// Lazy reference251val testProvider: TaskProvider<Test> = tasks.test252 253testProvider {254    // lazy configuration255}256 257// Eagerly realized Test task, defeat configuration avoidance if done out of a lazy context258val test: Test = tasks.test.get()259----260 261For all other containers than `tasks`, accessors for elements are of type `NamedDomainObjectProvider<T>` and provide the same behavior.262 263[[sec:kotlin_using_standard_api]]264=== Understanding what to do when type-safe model accessors are not available265 266Consider the sample build script shown above that demonstrates the use of type-safe accessors.267The following sample is exactly the same except that is uses the `apply()` method to apply the plugin.268The build script can not use type-safe accessors in this case because the `apply()` call happens in the body of the build script.269You have to use other techniques instead, as demonstrated here:270 271.Configuring plugins without type-safe accessors272====273include::sample[dir=""snippets/kotlinDsl/noAccessors/kotlin"",files=""build.gradle.kts[tags=no-accessors]""]274====275 276Type-safe accessors are unavailable for model elements contributed by the following:277 278 * Plugins applied via the `apply(plugin = ""id"")` method279 * The project build script280 * Script plugins, via `apply(from = ""script-plugin.gradle.kts"")`281 * Plugins applied via <<sec:kotlin_cross_project_configuration,cross-project configuration>>282 283You also can not use type-safe accessors in Binary Gradle plugins implemented in Kotlin.284 285If you can't find a type-safe accessor, _fall back to using the normal API_ for the corresponding types.286To do that, you need to know the names and/or types of the configured model elements.287We'll now show you how those can be discovered by looking at the above script in detail.288 289==== Artifact configurations290 291The following sample demonstrates how to reference and configure artifact configurations without type accessors:292 293.Artifact configurations294====295include::sample[dir=""snippets/kotlinDsl/noAccessors/kotlin"",files=""build.gradle.kts[tags=dependencies]""]296====297 298The code looks similar to that for the type-safe accessors, except that the configuration names are string literals in this case.299You can use string literals for configuration names in dependency declarations and within the `configurations {}` block.300 301The IDE won't be able to help you discover the available configurations in this situation, but you can look them up either in the corresponding plugin's documentation or by running `gradle dependencies`.302 303==== Project extensions and conventions304 305Project extensions and <<#sec:kotlin_dsl_about_conventions,conventions>> have both a name and a unique type, but the Kotlin DSL only needs to know the type in order to configure them.306As the following sample shows for the `sourceSets {}` and `java {}` blocks from the original example build script, you can use the link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-project/configure.html[`configure<T>()`] function with the corresponding type to do that:307 308.Project extensions and conventions309====310include::sample[dir=""snippets/kotlinDsl/noAccessors/kotlin"",files=""build.gradle.kts[tags=project-extension]""]311====312 313Note that `sourceSets` is a Gradle extension on `Project` of type `SourceSetContainer` and `java` is an extension on `Project` of type `JavaPluginExtension`.314 315You can discover what extensions and conventions are available either by looking at the documentation for the applied plugins or by running `gradle kotlinDslAccessorsReport`, which prints the Kotlin code necessary to access the model elements contributed by all the applied plugins.316The report provides both names and types.317As a last resort, you can also check a plugin's source code, but that shouldn't be necessary in the majority of cases.318 319Note that you can also use the link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-project/the.html[`the<T>()`] function if you only need a reference to the extension or convention without configuring it, or if you want to perform a one-line configuration, like so:320 321[source,kotlin]322----323the<SourceSetContainer>()[""main""].srcDir(""src/core/java"")324----325 326The snippet above also demonstrates one way of configuring the elements of a project extension that is a container.327 328==== Elements in project-extension containers329 330Container-based project extensions, such as `SourceSetContainer`, also allow you to configure the elements held by them.331In our sample build script, we want to configure a source set named `main` within the source set container, which we can do by using the link:{javadocPath}/org/gradle/api/NamedDomainObjectCollection.html#named-java.lang.String-[named()] method in place of an accessor, like so:332 333.Elements of project extensions that are containers334====335include::sample[dir=""snippets/kotlinDsl/noAccessors/kotlin"",files=""build.gradle.kts[tags=project-container-extension]""]336====337 338All elements within a container-based project extension have a name, so you can use this technique in all such cases.339 340As for project extensions and conventions themselves, you can discover what elements are present in any container by either looking at the documentation of the applied plugins or by running `gradle kotlinDslAccessorsReport`.341And as a last resort, you may be able to view the plugin's source code to find out what it does, but that shouldn't be necessary in the majority of cases.342 343==== Tasks344 345Tasks are not managed through a container-based project extension, but they are part of a container that behaves in a similar way.346This means that you can configure tasks in the same way as you do for source sets, as you can see in this example:347 348.Tasks349====350include::sample[dir=""snippets/kotlinDsl/noAccessors/kotlin"",files=""build.gradle.kts[tags=tasks]""]351====352 353We are using the Gradle API to refer to the tasks by name and type, rather than using accessors.354Note that it's necessary to specify the type of the task explicitly, otherwise the script won't compile because the inferred type will be `Task`, not `Test`, and the `testLogging` property is specific to the `Test` task type.355You can, however, omit the type if you only need to configure properties or to call methods that are common to all tasks, i.e. they are declared on the `Task` interface.356 357One can discover what tasks are available by running `gradle tasks`. You can then find out the type of a given task by running `gradle help --task <taskName>`, as demonstrated here:358 359[source]360----361❯ ./gradlew help --task test362...363Type364     Test (org.gradle.api.tasks.testing.Test)365----366 367Note that the IDE can assist you with the required imports, so you only need the simple names of the types, i.e. without the package name part.368In this case, there's no need to import the `Test` task type as it is part of the Gradle API and is therefore <<kotlin_dsl#sec:implicit_imports,imported implicitly>>.369 370[[sec:kotlin_dsl_about_conventions]]371=== About conventions372 373Some of the Gradle core plugins expose configurability with the help of a so-called _convention_ object.374These serve a similar purpose to — and have now been superseded by — _extensions_.375Please avoid using convention objects when writing new plugins.376The long term plan is to migrate all Gradle core plugins to use extensions and remove the convention objects altogether.377 378As seen above, the Kotlin DSL provides accessors only for convention objects on `Project`.379There are situations that require you to interact with a Gradle plugin that uses convention objects on other types.380The Kotlin DSL provides the `withConvention(T::class) {}` extension function to do this:381 382.Configuring source set conventions383====384include::sample[dir=""snippets/kotlinDsl/sourceSetConvention/kotlin"",files=""build.gradle.kts[tags=source-set-convention]""]385====386 387This technique is most commonly required for source sets that are added by language plugins other than the Java Plugin, e.g. the Groovy Plugin and the Scala Plugin. You can see which plugins add which properties to source sets in the link:{groovyDslPath}/org.gradle.api.tasks.SourceSet.html[SourceSet] reference documentation.388 389[[kotdsl:multi_project_builds]]390[[sec:multi_project_builds]]391== Multi-project builds392 393As with single-project builds, you should try to use the `plugins {}` block in your multi-project builds so that you can use the type-safe accessors. Another consideration with multi-project builds is that you won't be able to use type-safe accessors when configuring subprojects within the root build script or with other forms of cross configuration between projects. We discuss both topics in more detail in the following sections.394 395[[sec:multi_project_builds_applying_plugins]]396=== Applying plugins397 398You can declare your plugins within the subprojects to which they apply, but we recommend that you also declare them within the root project build script. This makes it easier to keep plugin versions consistent across projects within a build. The approach also improves the performance of the build.399 400The <<plugins#sec:subprojects_plugins_dsl,Using Gradle plugins>> chapter explains how you can declare plugins in the root project build script with a version and then apply them to the appropriate subprojects' build scripts. What follows is an example of this approach using three subprojects and three plugins. Note how the root build script only declares the community plugins as the Java Library Plugin is tied to the version of Gradle you are using:401 402[[ex:multi_project_ratpack]]403.Declare plugin dependencies in the root build script using the `plugins {}` block404====405include::sample[dir=""snippets/kotlinDsl/multiProjectBuild/kotlin"",files=""settings.gradle.kts[tags=base];build.gradle.kts[tags=root];domain/build.gradle.kts[];infra/build.gradle.kts[];http/build.gradle.kts[]""]406====407 408If your build requires additional plugin repositories on top of the Gradle Plugin Portal, you should declare them in the `pluginManagement {}` block in your `settings.gradle.kts` file, like so:409 410.Declare additional plugin repositories411====412include::sample[dir=""snippets/kotlinDsl/multiProjectBuild/kotlin"",files=""settings.gradle.kts[tags=repositories]""]413====414 415Plugins fetched from a source other than the link:https://plugins.gradle.org/[Gradle Plugin Portal] can only be declared via the `plugins {}` block if they are published with their <<plugins#sec:plugin_markers,plugin marker artifacts>>.416 417NOTE: At the time of writing, all versions of the Android Plugin for Gradle up to 3.2.0 present in the `google()` repository lack plugin marker artifacts.418 419If those artifacts are missing, then you can't use the `plugins {}` block. You must instead fall back to declaring your plugin dependencies using the `buildscript {}` block in the root project build script. Here's an example of doing that for the Android Plugin:420 421.Declare plugin dependencies in the root build script using the `buildscript {}` block422====423include::sample[dir=""snippets/kotlinDsl/androidBuild/kotlin"",files=""settings.gradle.kts[tags=android];build.gradle.kts[tags=android-buildscript];lib/build.gradle.kts[tags=android];app/build.gradle.kts[tags=android]""]424====425 426This technique is not that different from what Android Studio produces when creating a new build.427The main difference is that the subprojects' build scripts in the above sample declare their plugins using the `plugins {}` block. This means that you can use type-safe accessors for the model elements that they contribute.428 429Note that you can't use this technique if you want to apply such a plugin either to the root project build script of a multi-project build (rather than solely to its subprojects) or to a single-project build. You'll need to use a different approach in those cases that we detail in <<kotlin_dsl#sec:plugins_resolution_strategy,another section>>.430 431[[sec:kotlin_cross_project_configuration]]432=== Cross-configuring projects433 434<<sharing_build_logic_between_subprojects#sec:convention_plugins_vs_cross_configuration,Cross project configuration>> is a mechanism by which you can configure a project from another project's build script. A common example is when you configure subprojects in the root project build script.435 436Taking this approach means that you won't be able to use type-safe accessors for model elements contributed by the plugins. You will instead have to rely on string literals and the standard Gradle APIs.437 438As an example, let's modify the <<ex:multi_project_ratpack,Java/Ratpack sample build>> to fully configure its subprojects from the root project build script:439 440.Cross-configuring projects441====442include::sample[dir=""snippets/kotlinDsl/multiProjectBuild/kotlin"",files=""settings.gradle.kts[tags=base];build.gradle.kts[tags=cross]""]443====444 445Note how we're using the `apply()` method to apply the plugins since the `plugins {}` block doesn't work in this context.446We are also using standard APIs instead of type-safe accessors to configure tasks, extensions and conventions — an approach that we discussed in <<kotlin_dsl#sec:kotlin_using_standard_api,more detail elsewhere>>.447 448[[sec:plugins_resolution_strategy]]449== When you can't use the `plugins {}` block450 451Plugins fetched from a source other than the link:https://plugins.gradle.org/[Gradle Plugin Portal] may or may not be usable with the `plugins {}` block.452It depends on how they have been published and, specifically, whether they have been published with the necessary <<plugins#sec:plugin_markers,plugin marker artifacts>>.453 454For example, the Android Plugin for Gradle is not published to the Gradle Plugin Portal and — at least up to version 3.2.0 of the plugin — the metadata required to resolve the artifacts for a given plugin identifier is not published to the Google repository.455 456If your build is a multi-project build and you don't need to apply such a plugin to your _root_ project, then you can get round this issue using the technique <<kotlin_dsl#sec:multi_project_builds_applying_plugins,described above>>.457For any other situation, keep reading.458 459[TIP]460====461When publishing plugins, please use Gradle's built-in <<java_gradle_plugin#java_gradle_plugin,Gradle Plugin Development Plugin>>.462It automates the publication of the metadata necessary to make your plugins usable with the `plugins {}` block.463====464 465We will show you in this section how to apply the Android Plugin to a single-project build or the root project of a multi-project build.466The goal is to instruct your build on how to map the `com.android.application` plugin identifier to a resolvable artifact.467This is done in two steps:468 469* Add a plugin repository to the build's settings script470* Map the plugin ID to the corresponding artifact coordinates471 472You accomplish both steps by configuring a `pluginManagement {}` block in the build's settings script.473To demonstrate, the following sample adds the `google()` repository — where the Android plugin is published — to the repository search list, and uses a `resolutionStrategy {}` block to map the `com.android.application` plugin ID to the `com.android.tools.build:gradle:<version>` artifact available in the `google()` repository:474 475.Mapping plugin IDs to dependency coordinates476====477include::sample[dir=""snippets/kotlinDsl/androidSingleBuild/kotlin"",files=""settings.gradle.kts[tags=android];build.gradle.kts[tags=android]""]478====479 480In fact, the above sample will work for all `com.android.*` plugins that are provided by the specified module. That's because the packaged module contains the details of which plugin ID maps to which plugin implementation class, using the properties-file mechanism described in the <<custom_plugins#sec:custom_plugins_standalone_project,Writing Custom Plugins>> chapter.481 482See the <<plugins#sec:plugin_management,Plugin Management>> section of the Gradle user manual for more information on the `pluginManagement {}` block and what it can be used for.483 484// [PL] It seems to me that this block of content should really be in a more generic part485//      of the user manual as it discusses techniques that apply outside of the Kotlin DSL.486//      In fact, it indicates missing content that this chapter should be able to link to.487//488// In the case of multi-project builds, this approach is similar to using a `buildscript {}` block in the root project build script to depend on third party plugins and then using `plugins {}` in your sub project build scripts to apply them.489// The main difference is that this approach means that the root project can also benefit from the `plugins {}` block and it is more aligned with Gradle best practices.490//491// [PL] We should also aim to avoid temporary information in the user manual that could492//      be out of date at any time.493// The same approach can be used to resolve plugins from composite builds, which link:https://github.com/gradle/gradle/issues/2528[do not expose plugin markers] yet.494// Simply map the plugin ID to the corresponding artifact coordinates as shown in the Android samples above.495 496 497// TODO ?498// [[sec:buildSrc]]499// == Using `buildSrc`500//501// 1. what is buildSrc -> link502// 2. apply the `kotlin-dsl` plugin, see below for the details503// 3. all dependencies added to `buildSrc/build.gradle.kts` will be available to all build scripts504// 3. all members from `buildSrc/src/main/kotlin` will be available to all build scripts505// 4. handy for constants, objects, functions, extension functions506// 5. perfect for Gradle Tasks, Gradle Plugins and DSL Extensions507 508 509[[kotdsl:containers]]510== Working with container objects511 512The Gradle build model makes heavy use of container objects (or just ""containers"").513For example, both `configurations` and `tasks` are container objects that contain `Configuration` and `Task` objects respectively.514Community plugins also contribute containers, like the `android.buildTypes` container contributed by the Android Plugin.515 516The Kotlin DSL provides several ways for build authors to interact with containers.517We look at each of those ways next, using the `tasks` container as an example.518 519[TIP]520====521Note that you can leverage the type-safe accessors described in <<kotdsl:accessor_applicability,another section>> if you are configuring existing elements on supported containers. That section also describes which containers support type-safe accessors.522====523 524 525=== Using the container API526 527All containers in Gradle implement link:{groovyDslPath}/org.gradle.api.NamedDomainObjectContainer.html#org.gradle.api.NamedDomainObjectContainer[NamedDomainObjectContainer<DomainObjectType>].528Some of them can contain objects of different types and implement link:{groovyDslPath}/org.gradle.api.PolymorphicDomainObjectContainer.html#org.gradle.api.PolymorphicDomainObjectContainer[PolymorphicDomainObjectContainer<BaseType>].529The simplest way to interact with containers is through these interfaces.530 531The following sample demonstrates how you can use the link:{groovyDslPath}/org.gradle.api.NamedDomainObjectContainer.html#org.gradle.api.NamedDomainObjectContainer:named(java.lang.String)[named()] method to configure existing tasks and the link:{groovyDslPath}/org.gradle.api.NamedDomainObjectContainer.html#org.gradle.api.NamedDomainObjectContainer:register(java.lang.String)[register()] method to create new ones.532 533.Using the container API534====535include::sample[dir=""snippets/kotlinDsl/containers-api/kotlin"",files=""build.gradle.kts[tags=api]""]536====537<1> Gets a reference of type `Task` to the existing task named `check`538<2> Registers a new untyped task named `myTask1`539<3> Gets a reference to the existing task named `compileJava` of type `JavaCompile`540<4> Registers a new task named `myCopy1` of type `Copy`541<5> Gets a reference to the existing (untyped) task named `assemble` and configures it — you can only configure properties and methods that are available on `Task` with this syntax542<6> Registers a new untyped task named `myTask2` and configures it — you can only configure properties and methods that are available on `Task` in this case543<7> Gets a reference to the existing task named `test` of type `Test` and configures it — in this case you have access to the properties and methods of the specified type544<8> Registers a new task named `myCopy2` of type `Copy` and configures it545 546[NOTE]547====548The above sample relies on the configuration avoidance APIs. If you need or want to eagerly configure or register container elements, simply replace `named()` with `getByName()` and `register()` with `create()`.549====550 551=== Using Kotlin delegated properties552 553Another way to interact with containers is via Kotlin delegated properties.554These are particularly useful if you need a reference to a container element that you can use elsewhere in the build.555In addition, Kotlin delegated properties can easily be renamed via IDE refactoring.556 557The following sample does the exact same things as the one in the previous section, but it uses delegated properties and reuses those references in place of string-literal task paths:558 559.Using Kotlin delegated properties560====561include::sample[dir=""snippets/kotlinDsl/containers-delegated-properties/kotlin"",files=""build.gradle.kts[tags=delegated-properties]""]562====563<1> Uses the reference to the `myTask1` task rather than a task path564 565 566[NOTE]567====568The above rely on configuration avoidance APIs. If you need to eagerly configure or register container elements simply replace link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-named-domain-object-container/existing.html[`existing()`] with link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-named-domain-object-container/getting.html[`getting()`] and link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-named-domain-object-container/registering.html[`registering()`] with link:{kotlinDslPath}/org.gradle.kotlin.dsl/org.gradle.api.-named-domain-object-container/creating.html[`creating()`].569====570 571=== Configuring multiple container elements together572 573When configuring several elements of a container one can group interactions in a block in order to avoid repeating the container's name on each interaction.574The following example uses a combination of type-safe accessors, the container API and Kotlin delegated properties:575 576.Container scope577====578include::sample[dir=""snippets/kotlinDsl/containers-scope/kotlin"",files=""build.gradle.kts[tags=scope]""]579====580 581// TODO decide if we should document this given the current limitation582// === The container scope string invoke extension583//584// .The container scope string invoke extension585// ====586// include::sample[dir=""snippets/kotlinDsl/containers-string-invoke/kotlin"",files=""build.gradle.kts[tags=string-invoke]""]587// ====588 589 590[[kotdsl:properties]]591== Working with runtime properties592 593Gradle has two main sources of properties that are defined at runtime: <<build_environment#sec:project_properties,_project properties_>> and <<writing_build_scripts#sec:extra_properties,_extra properties_>>.594The Kotlin DSL provides specific syntax for working with these types of properties, which we look at in the following sections.595 596=== Project properties597 598The Kotlin DSL allows you to access project properties by binding them via Kotlin delegated properties.599Here's a sample snippet that demonstrates the technique for a couple of project properties, one of which _must_ be defined:600 601.build.gradle.kts602[source,kotlin]603----604val myProperty: String by project  // <1>605val myNullableProperty: String? by project // <2>606----607<1> Makes the `myProperty` project property available via a `myProperty` delegated property — the project property must exist in this case, otherwise the build will fail when the build script attempts to use the `myProperty` value608<2> Does the same for the `myNullableProperty` project property, but the build won't fail on using the `myNullableProperty` value as long as you check for null (standard https://kotlinlang.org/docs/reference/null-safety.html[Kotlin rules for null safety] apply)609 610The same approach works in both settings and initialization scripts, except you use `by settings` and `by gradle` respectively in place of `by project`.611 612=== Extra properties613 614Extra properties are available on any object that implements the link:{groovyDslPath}/org.gradle.api.plugins.ExtensionAware.html#org.gradle.api.plugins.ExtensionAware[ExtensionAware] interface.615Kotlin DSL allows you to access extra properties and create new ones via delegated properties, using any of the `by extra` forms demonstrated in the following sample:616 617.build.gradle.kts618[source,kotlin]619----620val myNewProperty by extra(""initial value"")  // <1>621val myOtherNewProperty by extra { ""calculated initial value"" }  // <2>622 623val myProperty: String by extra  // <3>624val myNullableProperty: String? by extra  // <4>625----626<1> Creates a new extra property called `myNewProperty` in the current context (the project in this case) and initializes it with the value `""initial value""`, which also determines the property's _type_627<2> Create a new extra property whose initial value is calculated by the provided lambda628<3> Binds an existing extra property from the current context (the project in this case) to a `myProperty` reference629<4> Does the same as the previous line but allows the property to have a null value630 631This approach works for all Gradle scripts: project build scripts, script plugins, settings scripts and initialization scripts.632 633You can also access extra properties on a root project from a subproject using the following syntax:634 635.my-sub-project/build.gradle.kts636[source,kotlin]637----638val myNewProperty: String by rootProject.extra  // <1>639----640<1> Binds the root project's `myNewProperty` extra property to a reference of the same name641 642Extra properties aren't just limited to projects.643For example, `Task` extends `ExtensionAware`, so you can attach extra properties to tasks as well.644Here's an example that defines a new `myNewTaskProperty` on the `test` task and then uses that property to initialize another task:645 646.build.gradle.kts647[source,kotlin]648----649tasks {650    test {651        val reportType by extra(""dev"")  // <1>652        doLast {653            // Use 'suffix' for post processing of reports654        }655    }656 657    register<Zip>(""archiveTestReports"") {658        val reportType: String by test.get().extra  // <2>659        archiveAppendix.set(reportType)660        from(test.get().reports.html.destination)661    }662}663----664<1> Creates a new `reportType` extra property on the `test` task665<2> Makes the `test` task's `reportType` extra property available to configure the `archiveTestReports` task666 667If you're happy to use eager configuration rather than the configuration avoidance APIs, you could use a single, ""global"" property for the report type, like this:668 669.build.gradle.kts670[source,kotlin]671----672tasks.test.doLast { ... }673 674val testReportType by tasks.test.get().extra(""dev"")  // <1>675 676tasks.create<Zip>(""archiveTestReports"") {677    archiveAppendix.set(testReportType)  // <2>678    from(test.get().reports.html.destination)679}680----681<1> Creates and initializes an extra property on the `test` task, binding it to a ""global"" property682<2> Uses the ""global"" property to initialize the `archiveTestReports` task683 684There is one last syntax for extra properties that we should cover, one that treats `extra` as a map.685We recommend against using this in general as you lose the benefits of Kotlin's type checking and it prevents IDEs from providing as much support as they could.686However, it is more succinct than the delegated properties syntax and can reasonably be used if you only need to set the value of an extra property without referencing it later.687 688Here's a simple example demonstrating how to set and read extra properties using the map syntax:689 690.build.gradle.kts691[source,kotlin]692----693extra[""myNewProperty""] = ""initial value""  // <1>694 695tasks.create(""myTask"") {696    doLast {697        println(""Property: ${project.extra[""myNewProperty""]}"")  // <2>698    }699}700----701<1> Creates a new project extra property called `myNewProperty` and sets its value702<2> Reads the value from the project extra property we created — note the `project.` qualifier on `extra[...]`, otherwise Gradle will assume we want to read an extra property from the _task_703 704// === `Property`, `Provider` and `NamedDomainObjectProvider`705 706 707[[sec:kotlin-dsl_plugin]]708== The Kotlin DSL Plugin709 710The Kotlin DSL Plugin provides a convenient way to develop Kotlin-based projects that contribute build logic.711That includes <<organizing_gradle_projects#sec:build_sources,buildSrc projects>>, <<composite_builds#,included builds>> and <<custom_plugins#,Gradle plugins>>.712 713The plugin achieves this by doing the following:714 715 * Applies the link:https://kotlinlang.org/docs/reference/using-gradle.html#targeting-the-jvm[Kotlin Plugin], which adds support for compiling Kotlin source files.716 * Adds the `kotlin-stdlib-jdk8`, `kotlin-reflect` and `gradleKotlinDsl()` dependencies to the `compileOnly` and `testImplementation` configurations, which allows you to make use of those Kotlin libraries and the Gradle API in your Kotlin code.717 * Configures the Kotlin compiler with the same settings that are used for Kotlin DSL scripts, ensuring consistency between your build logic and those scripts.718 * Enables support for <<custom_plugins#sec:precompiled_plugins,precompiled script plugins>>.719 720[CAUTION]721.Avoid specifying a version for the `kotlin-dsl` plugin722====723Each Gradle release is meant to be used with a specific version of the `kotlin-dsl` plugin and compatibility between arbitrary Gradle releases and `kotlin-dsl` plugin versions is not guaranteed. Using an unexpected version of the `kotlin-dsl` plugin in a build will emit a warning and can cause hard to diagnose problems.724====725 726This is the basic configuration you need to use the plugin:727 728.Applying the Kotlin DSL Plugin to a `buildSrc` project729====730include::sample[dir=""snippets/kotlinDsl/kotlinDslPlugin/kotlin"",files=""buildSrc/build.gradle.kts[tags=apply]""]731====732 733[[sec:kotlin]]734== The embedded Kotlin735 736Gradle embeds Kotlin in order to provide support for Kotlin-based scripts.737 738=== Kotlin versions739 740Gradle ships with `kotlin-compiler-embeddable` plus matching versions of `kotlin-stdlib` and `kotlin-reflect` libraries. For example, Gradle 4.3 ships with the Kotlin DSL v0.12.1 that includes Kotlin 1.1.51 versions of these modules. The `kotlin` package from those modules is visible through the Gradle classpath.741 742The link:https://kotlinlang.org/docs/reference/compatibility.html[compatibility guarantees] provided by Kotlin apply for both backward and forward compatibility.743 744==== Backward compatibility745 746Our approach is to only do backwards-breaking Kotlin upgrades on a major Gradle release. We will always clearly document which Kotlin version we ship and announce upgrade plans before a major release.747 748Plugin authors who want to stay compatible with older Gradle versions need to limit their API usage to a subset that is compatible with these old versions. It’s not really different from any other new API in Gradle. E.g. if we introduce a new API for dependency resolution and a plugin wants to use that API, then they either need to drop support for older Gradle versions or they need to do some clever organization of their code to only execute the new code path on newer versions.749 750==== Forward compatibility751 752The biggest issue is the compatibility between the external `kotlin-gradle-plugin` version and the `kotlin-stdlib` version shipped with Gradle. More generally, between any plugin that transitively depends on `kotlin-stdlib` and its version shipped with Gradle. As long as the combination is compatible everything should work. This will become less of an issue as the language matures.753 754[[sec:kotlin_compiler_arguments]]755=== Kotlin compiler arguments756 757These are the Kotlin compiler arguments used for compiling Kotlin DSL scripts and Kotlin sources and scripts in a project that has the `kotlin-dsl` plugin applied:758 759`-jvm-target=1.8`::760Sets the target version of the generated JVM bytecode to `1.8`.761 762`-Xjsr305=strict`::763Sets up Kotlin's Java interoperability to strictly follow JSR-305 annotations for increased null safety.764See link:https://kotlinlang.org/docs/reference/java-interop.html#compiler-configuration[Calling Java code from Kotlin] in the Kotlin documentation for more information.765 766[[sec:interoperability]]767== Interoperability768 769When mixing languages in your build logic, you may have to cross language boundaries.770An extreme example would be a build that uses tasks and plugins that are implemented in Java, Groovy and Kotlin, while also using both Kotlin DSL and Groovy DSL build scripts.771 772Quoting the Kotlin reference documentation:773 774> Kotlin is designed with Java Interoperability in mind. Existing Java code can be called from Kotlin in a natural way, and Kotlin code can be used from Java rather smoothly as well.775 776Both link:{kotlin-reference}java-interop.html[calling Java from Kotlin] and link:{kotlin-reference}java-to-kotlin-interop.html[calling Kotlin from Java] are very well covered in the Kotlin reference documentation.777 778The same mostly applies to interoperability with Groovy code.779In addition, the Kotlin DSL provides several ways to opt into Groovy semantics, which we look at next.780 781=== Static extensions782 783Both the Groovy and Kotlin languages support extending existing classes via link:https://groovy-lang.org/metaprogramming.html#_extension_modules[Groovy Extension modules] and link:{kotlin-reference}extensions.html[Kotlin extensions].784 785To call a Kotlin extension function from Groovy, call it as a static function, passing the receiver as the first parameter:786 787.Calling a Kotlin extension from Groovy788====789include::sample[dir=""snippets/kotlinDsl/interoperability-static-extensions/kotlin"",files=""build.gradle[tags=kotlin-from-groovy]""]790====791 792Kotlin extension functions are package-level functions and you can learn how to locate the name of the type declaring a given Kotlin extension in the link:{kotlin-reference}java-to-kotlin-interop.html#package-level-functions[Package-Level Functions] section of the Kotlin reference documentation.793 794To call a Groovy extension method from Kotlin, the same approach applies: call it as a static function passing the receiver as the first parameter.795Here's an example:796 797.Calling a Groovy extension from Kotlin798====799include::sample[dir=""snippets/kotlinDsl/interoperability-static-extensions/kotlin"",files=""build.gradle.kts[tags=groovy-from-kotlin]""]800====801 802=== Named parameters and default arguments803 804Both the Groovy and Kotlin languages support named function parameters and default arguments, although they are implemented very differently.805Kotlin has fully-fledged support for both, as described in the Kotlin language reference under link:{kotlin-reference}functions.html#named-arguments[named arguments] and link:{kotlin-reference}functions.html#default-arguments[default arguments].806Groovy implements link:https://groovy-lang.org/objectorientation.html#_named_arguments[named arguments] in a non-type-safe way based on a `Map<String, ?>` parameter, which means they cannot be combined with link:https://groovy-lang.org/objectorientation.html#_default_arguments[default arguments].807In other words, you can only use one or the other in Groovy for any given method.808 809==== Calling Kotlin from Groovy810 811To call a Kotlin function that has named arguments from Groovy, just use a normal method call with positional parameters.812There is no way to provide values by argument name.813 814To call a Kotlin function that has default arguments from Groovy, always pass values for all the function parameters.815 816==== Calling Groovy from Kotlin817 818To call a Groovy function with named arguments from Kotlin, you need to pass a `Map<String, ?>`, as shown in this example:819 820.Call Groovy function with named arguments from Kotlin821[.multi-language-sample]822====823.build.gradle.kts824[source, kotlin]825----826groovyNamedArgumentTakingMethod(mapOf(827    ""parameterName"" to ""value"",828    ""other"" to 42,829    ""and"" to aReference))830----831====832 833To call a Groovy function with default arguments from Kotlin, always pass values for all the parameters.834 835=== Groovy closures from Kotlin836 837You may sometimes have to call Groovy methods that take link:https://groovy-lang.org/closures.html[Closure] arguments from Kotlin code.838For example, some third-party plugins written in Groovy expect closure arguments.839 840[NOTE]841====842Gradle plugins written in any language should prefer the type `Action<T>` type in place of closures. Groovy closures and Kotlin lambdas are automatically mapped to arguments of that type.843====844 845In order to provide a way to construct closures while preserving Kotlin's strong typing, two helper methods exist:846 847* `closureOf<T> {}`848* `delegateClosureOf<T> {}`849 850Both methods are useful in different circumstances and depend upon the method you are passing the `Closure` instance into.851 852Some plugins expect simple closures, as with the link:{plugin-portal}plugin/com.jfrog.bintray[Bintray] plugin:853 854.Use `closureOf<T> {}`855====856include::sample[dir=""snippets/kotlinDsl/interoperability-closure-of/kotlin"",files=""build.gradle.kts[tags=closureOf]""]857====858 859In other cases, like with the link:{plugin-portal}plugin/org.gretty[Gretty Plugin] when configuring farms, the plugin expects a delegate closure:860 861.Use `delegateClosureOf<T> {}`862====863include::sample[dir=""snippets/kotlinDsl/interoperability-delegate-closure-of/kotlin"",files=""build.gradle.kts[tags=delegateClosureOf]""]864====865 866There sometimes isn't a good way to tell, from looking at the source code, which version to use.867Usually, if you get a `NullPointerException` with `closureOf<T> {}`, using `delegateClosureOf<T> {}`868will resolve the problem.869 870These two utility functions are useful for _configuration closures_, but some plugins might expect Groovy closures for other purposes.871The `KotlinClosure0` to `KotlinClosure2` types allows adapting Kotlin functions to Groovy closures with more flexibility.872 873.Use `KotlinClosureX` types874====875include::sample[dir=""snippets/kotlinDsl/interoperability-kotlinClosure/kotlin"",files=""build.gradle.kts[tags=kotlinClosure]""]876====877 878Also see the link:{kotlin-dsl-samples}groovy-interop[groovy-interop] sample.879 880=== The Kotlin DSL Groovy Builder881 882If some plugin makes heavy use of link:https://groovy-lang.org/metaprogramming.html[Groovy metaprogramming], then using it from Kotlin or Java or any statically-compiled language can be very cumbersome.883 884The Kotlin DSL provides a `withGroovyBuilder {}` utility extension that attaches the Groovy metaprogramming semantics to objects of type `Any`.885The following example demonstrates several features of the method on the object `target`:886 887.Use `withGroovyBuilder {}`888====889include::sample[dir=""snippets/kotlinDsl/interoperability-groovy-builder/kotlin"",files=""build.gradle.kts[tags=withGroovyBuilder]""]890====891<1> The receiver is a link:https://docs.groovy-lang.org/latest/html/api/groovy/lang/GroovyObject.html[GroovyObject] and provides Kotlin helpers892<2> The `GroovyObject` API is available893<3> Invoke the `methodName` method, passing some parameters894<4> Configure the `blockName` property, maps to a `Closure` taking method invocation895<5> Invoke `another` method taking named arguments, maps to a Groovy named arguments `Map<String, ?>` taking method invocation896 897The link:{kotlin-dsl-samples}maven-plugin[maven-plugin] sample demonstrates the use of the `withGroovyBuilder()` utility extensions for configuring the `uploadArchives` task to <<maven_plugin#sec:deploying_to_a_maven_repository, deploy to a Maven repository>> with a custom POM using Gradle's core <<maven_plugin#, Maven Plugin>>.898Note that the recommended <<publishing_maven#, Maven Publish Plugin>> provides a type-safe and Kotlin-friendly DSL that allows you to easily do <<publishing_maven#sec:modifying_the_generated_pom, the same and more>> without resorting to `withGroovyBuilder()`.899 900[[using_a_groovy_script]]901=== Using a Groovy script902 903Another option when dealing with problematic plugins that assume a Groovy DSL build script is to configure them in a Groovy DSL build script that is applied from the main Kotlin DSL build script:904 905.Using a Groovy script906====907[.multi-language-sample]908=====909.build.gradle.kts910[source, kotlin]911----912plugins {913    id(""dynamic-groovy-plugin"") version ""1.0""               <1>914}915apply(from = ""dynamic-groovy-plugin-configuration.gradle"")  <2>916----917=====918====919 920====921[.multi-language-sample]922=====923.dynamic-groovy-plugin-configuration.gradle924[source, groovy]925----926native {                                                    <3>927    dynamic {928        groovy as Usual929    }930}931----932=====933====934<1> The Kotlin build script requests and applies the plugin935<2> The Kotlin build script applies the Groovy script936<3> The Groovy script uses dynamic Groovy to configure plugin937 938[[kotdsl:limitations]]939== Limitations940 941* The Kotlin DSL is link:https://github.com/gradle/kotlin-dsl/issues/902[known to be slower than the Groovy DSL] on first use, for example with clean checkouts or on ephemeral continuous integration agents.942Changing something in the _buildSrc_ directory also has an impact as it invalidates build-script caching.943The main reason for this is the slower script compilation for Kotlin DSL.944* In IntelliJ IDEA, you must link:https://www.jetbrains.com/help/idea/gradle.html#gradle_import[import your project from the Gradle model] in order to get content assist and refactoring support for your Kotlin DSL build scripts.945* The Kotlin DSL will not support the `model {}` block, which is part of the link:https://blog.gradle.org/state-and-future-of-the-gradle-software-model[discontinued Gradle Software Model].946However, you _can_ apply model rules from scripts — see the link:{kotlin-dsl-samples}model-rules[model rules] sample for more information.947* We recommend against enabling the incubating <<multi_project_configuration_and_execution#sec:configuration_on_demand,configuration on demand>> feature as it can lead to very hard-to-diagnose problems.948 949If you run into trouble or discover a suspected bug, please report the issue in the link:{gradle-issues}[Gradle issue tracker].950 951",12104,False,2091.6735705982196,median952"[[netty-component]]953= Netty Component954//THIS FILE IS COPIED: EDIT THE SOURCE FILE:955:page-source: components/camel-netty/src/main/docs/netty-component.adoc956:docTitle: Netty957:artifactId: camel-netty958:description: Socket level networking using TCP or UDP with the Netty 4.x.959:since: 2.14960:supportLevel: Stable961:component-header: Both producer and consumer are supported962 963*Since Camel {since}*964 965*{component-header}*966 967The Netty component in Camel is a socket communication component,968based on the http://netty.io/[Netty] project version 4. +969 Netty is a NIO client server framework which enables quick and easy970development of networkServerInitializerFactory applications such as971protocol servers and clients. +972 Netty greatly simplifies and streamlines network programming such as973TCP and UDP socket server.974 975This camel component supports both producer and consumer endpoints.976 977The Netty component has several options and allows fine-grained control978of a number of TCP/UDP communication parameters (buffer sizes,979keepAlives, tcpNoDelay, etc) and facilitates both In-Only and In-Out980communication on a Camel route.981 982Maven users will need to add the following dependency to their `pom.xml`983for this component:984 985[source,xml]986----987<dependency>988    <groupId>org.apache.camel</groupId>989    <artifactId>camel-netty</artifactId>990    <version>x.x.x</version>991    <!-- use the same version as your Camel core version -->992</dependency>993----994 995== URI format996 997The URI scheme for a netty component is as follows998 999[source,text]1000----1001netty:tcp://0.0.0.0:99999[?options]1002netty:udp://remotehost:99999/[?options]1003----1004 1005This component supports producer and consumer endpoints for both TCP and1006UDP.1007 1008You can append query options to the URI in the following format,1009`?option=value&option=value&...`1010 1011== Options1012 1013// component options: START1014The Netty component supports 72 options, which are listed below.1015 1016 1017 1018[width=""100%"",cols=""2,5,^1,2"",options=""header""]1019|===1020| Name | Description | Default | Type1021| *configuration* (common) | To use the NettyConfiguration as configuration when creating endpoints. |  | NettyConfiguration1022| *disconnect* (common) | Whether or not to disconnect(close) from Netty Channel right after use. Can be used for both consumer and producer. | false | boolean1023| *keepAlive* (common) | Setting to ensure socket is not closed due to inactivity | true | boolean1024| *reuseAddress* (common) | Setting to facilitate socket multiplexing | true | boolean1025| *reuseChannel* (common) | This option allows producers and consumers (in client mode) to reuse the same Netty Channel for the lifecycle of processing the Exchange. This is useful if you need to call a server multiple times in a Camel route and want to use the same network connection. When using this, the channel is not returned to the connection pool until the Exchange is done; or disconnected if the disconnect option is set to true. The reused Channel is stored on the Exchange as an exchange property with the key NettyConstants#NETTY_CHANNEL which allows you to obtain the channel during routing and use it as well. | false | boolean1026| *sync* (common) | Setting to set endpoint as one-way or request-response | true | boolean1027| *tcpNoDelay* (common) | Setting to improve TCP protocol performance | true | boolean1028| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean1029| *broadcast* (consumer) | Setting to choose Multicast over UDP | false | boolean1030| *clientMode* (consumer) | If the clientMode is true, netty consumer will connect the address as a TCP client. | false | boolean1031| *reconnect* (consumer) | Used only in clientMode in consumer, the consumer will attempt to reconnect on disconnection if this is enabled | true | boolean1032| *reconnectInterval* (consumer) | Used if reconnect and clientMode is enabled. The interval in milli seconds to attempt reconnection | 10000 | int1033| *backlog* (consumer) | Allows to configure a backlog for netty consumer (server). Note the backlog is just a best effort depending on the OS. Setting this option to a value such as 200, 500 or 1000, tells the TCP stack how long the accept queue can be If this option is not configured, then the backlog depends on OS setting. |  | int1034| *bossCount* (consumer) | When netty works on nio mode, it uses default bossCount parameter from Netty, which is 1. User can use this option to override the default bossCount from Netty | 1 | int1035| *bossGroup* (consumer) | Set the BossGroup which could be used for handling the new connection of the server side across the NettyEndpoint |  | EventLoopGroup1036| *disconnectOnNoReply* (consumer) | If sync is enabled then this option dictates NettyConsumer if it should disconnect where there is no reply to send back. | true | boolean1037| *executorService* (consumer) | To use the given EventExecutorGroup. |  | EventExecutorGroup1038| *maximumPoolSize* (consumer) | Sets a maximum thread pool size for the netty consumer ordered thread pool. The default size is 2 x cpu_core plus 1. Setting this value to eg 10 will then use 10 threads unless 2 x cpu_core plus 1 is a higher value, which then will override and be used. For example if there are 8 cores, then the consumer thread pool will be 17. This thread pool is used to route messages received from Netty by Camel. We use a separate thread pool to ensure ordering of messages and also in case some messages will block, then nettys worker threads (event loop) wont be affected. |  | int1039| *nettyServerBootstrapFactory* (consumer) | To use a custom NettyServerBootstrapFactory |  | NettyServerBootstrapFactory1040| *networkInterface* (consumer) | When using UDP then this option can be used to specify a network interface by its name, such as eth0 to join a multicast group. |  | String1041| *noReplyLogLevel* (consumer) | If sync is enabled this option dictates NettyConsumer which logging level to use when logging a there is no reply to send back. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | WARN | LoggingLevel1042| *serverClosedChannelException CaughtLogLevel* (consumer) | If the server (NettyConsumer) catches an java.nio.channels.ClosedChannelException then its logged using this logging level. This is used to avoid logging the closed channel exceptions, as clients can disconnect abruptly and then cause a flood of closed exceptions in the Netty server. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | DEBUG | LoggingLevel1043| *serverExceptionCaughtLogLevel* (consumer) | If the server (NettyConsumer) catches an exception then its logged using this logging level. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | WARN | LoggingLevel1044| *serverInitializerFactory* (consumer) | To use a custom ServerInitializerFactory |  | ServerInitializerFactory1045| *usingExecutorService* (consumer) | Whether to use ordered thread pool, to ensure events are processed orderly on the same channel. | true | boolean1046| *connectTimeout* (producer) | Time to wait for a socket connection to be available. Value is in milliseconds. | 10000 | int1047| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean1048| *requestTimeout* (producer) | Allows to use a timeout for the Netty producer when calling a remote server. By default no timeout is in use. The value is in milli seconds, so eg 30000 is 30 seconds. The requestTimeout is using Netty's ReadTimeoutHandler to trigger the timeout. |  | long1049| *clientInitializerFactory* (producer) | To use a custom ClientInitializerFactory |  | ClientInitializerFactory1050| *correlationManager* (producer) | To use a custom correlation manager to manage how request and reply messages are mapped when using request/reply with the netty producer. This should only be used if you have a way to map requests together with replies such as if there is correlation ids in both the request and reply messages. This can be used if you want to multiplex concurrent messages on the same channel (aka connection) in netty. When doing this you must have a way to correlate the request and reply messages so you can store the right reply on the inflight Camel Exchange before its continued routed. We recommend extending the TimeoutCorrelationManagerSupport when you build custom correlation managers. This provides support for timeout and other complexities you otherwise would need to implement as well. See also the producerPoolEnabled option for more details. |  | NettyCamelStateCorrelationManager1051| *lazyChannelCreation* (producer) | Channels can be lazily created to avoid exceptions, if the remote server is not up and running when the Camel producer is started. | true | boolean1052| *producerPoolEnabled* (producer) | Whether producer pool is enabled or not. Important: If you turn this off then a single shared connection is used for the producer, also if you are doing request/reply. That means there is a potential issue with interleaved responses if replies comes back out-of-order. Therefore you need to have a correlation id in both the request and reply messages so you can properly correlate the replies to the Camel callback that is responsible for continue processing the message in Camel. To do this you need to implement NettyCamelStateCorrelationManager as correlation manager and configure it via the correlationManager option. See also the correlationManager option for more details. | true | boolean1053| *producerPoolMaxActive* (producer) | Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit. | -1 | int1054| *producerPoolMaxIdle* (producer) | Sets the cap on the number of idle instances in the pool. | 100 | int1055| *producerPoolMinEvictableIdle* (producer) | Sets the minimum amount of time (value in millis) an object may sit idle in the pool before it is eligible for eviction by the idle object evictor. | 300000 | long1056| *producerPoolMinIdle* (producer) | Sets the minimum number of instances allowed in the producer pool before the evictor thread (if active) spawns new objects. |  | int1057| *udpConnectionlessSending* (producer) | This option supports connection less udp sending which is a real fire and forget. A connected udp send receive the PortUnreachableException if no one is listen on the receiving port. | false | boolean1058| *useByteBuf* (producer) | If the useByteBuf is true, netty producer will turn the message body into ByteBuf before sending it out. | false | boolean1059| *allowSerializedHeaders* (advanced) | Only used for TCP when transferExchange is true. When set to true, serializable objects in headers and properties will be added to the exchange. Otherwise Camel will exclude any non-serializable objects and log it at WARN level. | false | boolean1060| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean1061| *channelGroup* (advanced) | To use a explicit ChannelGroup. |  | ChannelGroup1062| *nativeTransport* (advanced) | Whether to use native transport instead of NIO. Native transport takes advantage of the host operating system and is only supported on some platforms. You need to add the netty JAR for the host operating system you are using. See more details at: \\http://netty.io/wiki/native-transports.html | false | boolean1063| *options* (advanced) | Allows to configure additional netty options using option. as prefix. For example option.child.keepAlive=false to set the netty option child.keepAlive=false. See the Netty documentation for possible options that can be used. |  | Map1064| *receiveBufferSize* (advanced) | The TCP/UDP buffer sizes to be used during inbound communication. Size is bytes. | 65536 | int1065| *receiveBufferSizePredictor* (advanced) | Configures the buffer size predictor. See details at Jetty documentation and this mail thread. |  | int1066| *sendBufferSize* (advanced) | The TCP/UDP buffer sizes to be used during outbound communication. Size is bytes. | 65536 | int1067| *transferExchange* (advanced) | Only used for TCP. You can transfer the exchange over the wire instead of just the body. The following fields are transferred: In body, Out body, fault body, In headers, Out headers, fault headers, exchange properties, exchange exception. This requires that the objects are serializable. Camel will exclude any non-serializable objects and log it at WARN level. | false | boolean1068| *udpByteArrayCodec* (advanced) | For UDP only. If enabled the using byte array codec instead of Java serialization protocol. | false | boolean1069| *workerCount* (advanced) | When netty works on nio mode, it uses default workerCount parameter from Netty (which is cpu_core_threads x 2). User can use this option to override the default workerCount from Netty. |  | int1070| *workerGroup* (advanced) | To use a explicit EventLoopGroup as the boss thread pool. For example to share a thread pool with multiple consumers or producers. By default each consumer or producer has their own worker pool with 2 x cpu count core threads. |  | EventLoopGroup1071| *allowDefaultCodec* (codec) | The netty component installs a default codec if both, encoder/decoder is null and textline is false. Setting allowDefaultCodec to false prevents the netty component from installing a default codec as the first element in the filter chain. | true | boolean1072| *autoAppendDelimiter* (codec) | Whether or not to auto append missing end delimiter when sending using the textline codec. | true | boolean1073| *decoderMaxLineLength* (codec) | The max line length to use for the textline codec. | 1024 | int1074| *decoders* (codec) | A list of decoders to be used. You can use a String which have values separated by comma, and have the values be looked up in the Registry. Just remember to prefix the value with # so Camel knows it should lookup. |  | List1075| *delimiter* (codec) | The delimiter to use for the textline codec. Possible values are LINE and NULL. The value can be one of: LINE, NULL | LINE | TextLineDelimiter1076| *encoders* (codec) | A list of encoders to be used. You can use a String which have values separated by comma, and have the values be looked up in the Registry. Just remember to prefix the value with # so Camel knows it should lookup. |  | List1077| *encoding* (codec) | The encoding (a charset name) to use for the textline codec. If not provided, Camel will use the JVM default Charset. |  | String1078| *textline* (codec) | Only used for TCP. If no codec is specified, you can use this flag to indicate a text line based codec; if not specified or the value is false, then Object Serialization is assumed over TCP - however only Strings are allowed to be serialized by default. | false | boolean1079| *enabledProtocols* (security) | Which protocols to enable when using SSL | TLSv1,TLSv1.1,TLSv1.2 | String1080| *keyStoreFile* (security) | Client side certificate keystore to be used for encryption |  | File1081| *keyStoreFormat* (security) | Keystore format to be used for payload encryption. Defaults to JKS if not set |  | String1082| *keyStoreResource* (security) | Client side certificate keystore to be used for encryption. Is loaded by default from classpath, but you can prefix with classpath:, file:, or http: to load the resource from different systems. |  | String1083| *needClientAuth* (security) | Configures whether the server needs client authentication when using SSL. | false | boolean1084| *passphrase* (security) | Password setting to use in order to encrypt/decrypt payloads sent using SSH |  | String1085| *securityProvider* (security) | Security provider to be used for payload encryption. Defaults to SunX509 if not set. |  | String1086| *ssl* (security) | Setting to specify whether SSL encryption is applied to this endpoint | false | boolean1087| *sslClientCertHeaders* (security) | When enabled and in SSL mode, then the Netty consumer will enrich the Camel Message with headers having information about the client certificate such as subject name, issuer name, serial number, and the valid date range. | false | boolean1088| *sslContextParameters* (security) | To configure security using SSLContextParameters |  | SSLContextParameters1089| *sslHandler* (security) | Reference to a class that could be used to return an SSL Handler |  | SslHandler1090| *trustStoreFile* (security) | Server side certificate keystore to be used for encryption |  | File1091| *trustStoreResource* (security) | Server side certificate keystore to be used for encryption. Is loaded by default from classpath, but you can prefix with classpath:, file:, or http: to load the resource from different systems. |  | String1092| *useGlobalSslContextParameters* (security) | Enable usage of global SSL context parameters. | false | boolean1093|===1094// component options: END1095 1096 1097// endpoint options: START1098The Netty endpoint is configured using URI syntax:1099 1100----1101netty:protocol:host:port1102----1103 1104with the following path and query parameters:1105 1106=== Path Parameters (3 parameters):1107 1108 1109[width=""100%"",cols=""2,5,^1,2"",options=""header""]1110|===1111| Name | Description | Default | Type1112| *protocol* | *Required* The protocol to use which can be tcp or udp. The value can be one of: tcp, udp |  | String1113| *host* | *Required* The hostname. For the consumer the hostname is localhost or 0.0.0.0. For the producer the hostname is the remote host to connect to |  | String1114| *port* | *Required* The host port number |  | int1115|===1116 1117 1118=== Query Parameters (71 parameters):1119 1120 1121[width=""100%"",cols=""2,5,^1,2"",options=""header""]1122|===1123| Name | Description | Default | Type1124| *disconnect* (common) | Whether or not to disconnect(close) from Netty Channel right after use. Can be used for both consumer and producer. | false | boolean1125| *keepAlive* (common) | Setting to ensure socket is not closed due to inactivity | true | boolean1126| *reuseAddress* (common) | Setting to facilitate socket multiplexing | true | boolean1127| *reuseChannel* (common) | This option allows producers and consumers (in client mode) to reuse the same Netty Channel for the lifecycle of processing the Exchange. This is useful if you need to call a server multiple times in a Camel route and want to use the same network connection. When using this, the channel is not returned to the connection pool until the Exchange is done; or disconnected if the disconnect option is set to true. The reused Channel is stored on the Exchange as an exchange property with the key NettyConstants#NETTY_CHANNEL which allows you to obtain the channel during routing and use it as well. | false | boolean1128| *sync* (common) | Setting to set endpoint as one-way or request-response | true | boolean1129| *tcpNoDelay* (common) | Setting to improve TCP protocol performance | true | boolean1130| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean1131| *broadcast* (consumer) | Setting to choose Multicast over UDP | false | boolean1132| *clientMode* (consumer) | If the clientMode is true, netty consumer will connect the address as a TCP client. | false | boolean1133| *reconnect* (consumer) | Used only in clientMode in consumer, the consumer will attempt to reconnect on disconnection if this is enabled | true | boolean1134| *reconnectInterval* (consumer) | Used if reconnect and clientMode is enabled. The interval in milli seconds to attempt reconnection | 10000 | int1135| *backlog* (consumer) | Allows to configure a backlog for netty consumer (server). Note the backlog is just a best effort depending on the OS. Setting this option to a value such as 200, 500 or 1000, tells the TCP stack how long the accept queue can be If this option is not configured, then the backlog depends on OS setting. |  | int1136| *bossCount* (consumer) | When netty works on nio mode, it uses default bossCount parameter from Netty, which is 1. User can use this option to override the default bossCount from Netty | 1 | int1137| *bossGroup* (consumer) | Set the BossGroup which could be used for handling the new connection of the server side across the NettyEndpoint |  | EventLoopGroup1138| *disconnectOnNoReply* (consumer) | If sync is enabled then this option dictates NettyConsumer if it should disconnect where there is no reply to send back. | true | boolean1139| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler1140| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. The value can be one of: InOnly, InOut, InOptionalOut |  | ExchangePattern1141| *nettyServerBootstrapFactory* (consumer) | To use a custom NettyServerBootstrapFactory |  | NettyServerBootstrapFactory1142| *networkInterface* (consumer) | When using UDP then this option can be used to specify a network interface by its name, such as eth0 to join a multicast group. |  | String1143| *noReplyLogLevel* (consumer) | If sync is enabled this option dictates NettyConsumer which logging level to use when logging a there is no reply to send back. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | WARN | LoggingLevel1144| *serverClosedChannelException CaughtLogLevel* (consumer) | If the server (NettyConsumer) catches an java.nio.channels.ClosedChannelException then its logged using this logging level. This is used to avoid logging the closed channel exceptions, as clients can disconnect abruptly and then cause a flood of closed exceptions in the Netty server. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | DEBUG | LoggingLevel1145| *serverExceptionCaughtLogLevel* (consumer) | If the server (NettyConsumer) catches an exception then its logged using this logging level. The value can be one of: TRACE, DEBUG, INFO, WARN, ERROR, OFF | WARN | LoggingLevel1146| *serverInitializerFactory* (consumer) | To use a custom ServerInitializerFactory |  | ServerInitializerFactory1147| *usingExecutorService* (consumer) | Whether to use ordered thread pool, to ensure events are processed orderly on the same channel. | true | boolean1148| *connectTimeout* (producer) | Time to wait for a socket connection to be available. Value is in milliseconds. | 10000 | int1149| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean1150| *requestTimeout* (producer) | Allows to use a timeout for the Netty producer when calling a remote server. By default no timeout is in use. The value is in milli seconds, so eg 30000 is 30 seconds. The requestTimeout is using Netty's ReadTimeoutHandler to trigger the timeout. |  | long1151| *clientInitializerFactory* (producer) | To use a custom ClientInitializerFactory |  | ClientInitializerFactory1152| *correlationManager* (producer) | To use a custom correlation manager to manage how request and reply messages are mapped when using request/reply with the netty producer. This should only be used if you have a way to map requests together with replies such as if there is correlation ids in both the request and reply messages. This can be used if you want to multiplex concurrent messages on the same channel (aka connection) in netty. When doing this you must have a way to correlate the request and reply messages so you can store the right reply on the inflight Camel Exchange before its continued routed. We recommend extending the TimeoutCorrelationManagerSupport when you build custom correlation managers. This provides support for timeout and other complexities you otherwise would need to implement as well. See also the producerPoolEnabled option for more details. |  | NettyCamelStateCorrelationManager1153| *lazyChannelCreation* (producer) | Channels can be lazily created to avoid exceptions, if the remote server is not up and running when the Camel producer is started. | true | boolean1154| *producerPoolEnabled* (producer) | Whether producer pool is enabled or not. Important: If you turn this off then a single shared connection is used for the producer, also if you are doing request/reply. That means there is a potential issue with interleaved responses if replies comes back out-of-order. Therefore you need to have a correlation id in both the request and reply messages so you can properly correlate the replies to the Camel callback that is responsible for continue processing the message in Camel. To do this you need to implement NettyCamelStateCorrelationManager as correlation manager and configure it via the correlationManager option. See also the correlationManager option for more details. | true | boolean1155| *producerPoolMaxActive* (producer) | Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. Use a negative value for no limit. | -1 | int1156| *producerPoolMaxIdle* (producer) | Sets the cap on the number of idle instances in the pool. | 100 | int1157| *producerPoolMinEvictableIdle* (producer) | Sets the minimum amount of time (value in millis) an object may sit idle in the pool before it is eligible for eviction by the idle object evictor. | 300000 | long1158| *producerPoolMinIdle* (producer) | Sets the minimum number of instances allowed in the producer pool before the evictor thread (if active) spawns new objects. |  | int1159| *udpConnectionlessSending* (producer) | This option supports connection less udp sending which is a real fire and forget. A connected udp send receive the PortUnreachableException if no one is listen on the receiving port. | false | boolean1160| *useByteBuf* (producer) | If the useByteBuf is true, netty producer will turn the message body into ByteBuf before sending it out. | false | boolean1161| *allowSerializedHeaders* (advanced) | Only used for TCP when transferExchange is true. When set to true, serializable objects in headers and properties will be added to the exchange. Otherwise Camel will exclude any non-serializable objects and log it at WARN level. | false | boolean1162| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean1163| *channelGroup* (advanced) | To use a explicit ChannelGroup. |  | ChannelGroup1164| *nativeTransport* (advanced) | Whether to use native transport instead of NIO. Native transport takes advantage of the host operating system and is only supported on some platforms. You need to add the netty JAR for the host operating system you are using. See more details at: \\http://netty.io/wiki/native-transports.html | false | boolean1165| *options* (advanced) | Allows to configure additional netty options using option. as prefix. For example option.child.keepAlive=false to set the netty option child.keepAlive=false. See the Netty documentation for possible options that can be used. |  | Map1166| *receiveBufferSize* (advanced) | The TCP/UDP buffer sizes to be used during inbound communication. Size is bytes. | 65536 | int1167| *receiveBufferSizePredictor* (advanced) | Configures the buffer size predictor. See details at Jetty documentation and this mail thread. |  | int1168| *sendBufferSize* (advanced) | The TCP/UDP buffer sizes to be used during outbound communication. Size is bytes. | 65536 | int1169| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean1170| *transferExchange* (advanced) | Only used for TCP. You can transfer the exchange over the wire instead of just the body. The following fields are transferred: In body, Out body, fault body, In headers, Out headers, fault headers, exchange properties, exchange exception. This requires that the objects are serializable. Camel will exclude any non-serializable objects and log it at WARN level. | false | boolean1171| *udpByteArrayCodec* (advanced) | For UDP only. If enabled the using byte array codec instead of Java serialization protocol. | false | boolean1172| *workerCount* (advanced) | When netty works on nio mode, it uses default workerCount parameter from Netty (which is cpu_core_threads x 2). User can use this option to override the default workerCount from Netty. |  | int1173| *workerGroup* (advanced) | To use a explicit EventLoopGroup as the boss thread pool. For example to share a thread pool with multiple consumers or producers. By default each consumer or producer has their own worker pool with 2 x cpu count core threads. |  | EventLoopGroup1174| *allowDefaultCodec* (codec) | The netty component installs a default codec if both, encoder/decoder is null and textline is false. Setting allowDefaultCodec to false prevents the netty component from installing a default codec as the first element in the filter chain. | true | boolean1175| *autoAppendDelimiter* (codec) | Whether or not to auto append missing end delimiter when sending using the textline codec. | true | boolean1176| *decoderMaxLineLength* (codec) | The max line length to use for the textline codec. | 1024 | int1177| *decoders* (codec) | A list of decoders to be used. You can use a String which have values separated by comma, and have the values be looked up in the Registry. Just remember to prefix the value with # so Camel knows it should lookup. |  | List1178| *delimiter* (codec) | The delimiter to use for the textline codec. Possible values are LINE and NULL. The value can be one of: LINE, NULL | LINE | TextLineDelimiter1179| *encoders* (codec) | A list of encoders to be used. You can use a String which have values separated by comma, and have the values be looked up in the Registry. Just remember to prefix the value with # so Camel knows it should lookup. |  | List1180| *encoding* (codec) | The encoding (a charset name) to use for the textline codec. If not provided, Camel will use the JVM default Charset. |  | String1181| *textline* (codec) | Only used for TCP. If no codec is specified, you can use this flag to indicate a text line based codec; if not specified or the value is false, then Object Serialization is assumed over TCP - however only Strings are allowed to be serialized by default. | false | boolean1182| *enabledProtocols* (security) | Which protocols to enable when using SSL | TLSv1,TLSv1.1,TLSv1.2 | String1183| *keyStoreFile* (security) | Client side certificate keystore to be used for encryption |  | File1184| *keyStoreFormat* (security) | Keystore format to be used for payload encryption. Defaults to JKS if not set |  | String1185| *keyStoreResource* (security) | Client side certificate keystore to be used for encryption. Is loaded by default from classpath, but you can prefix with classpath:, file:, or http: to load the resource from different systems. |  | String1186| *needClientAuth* (security) | Configures whether the server needs client authentication when using SSL. | false | boolean1187| *passphrase* (security) | Password setting to use in order to encrypt/decrypt payloads sent using SSH |  | String1188| *securityProvider* (security) | Security provider to be used for payload encryption. Defaults to SunX509 if not set. |  | String1189| *ssl* (security) | Setting to specify whether SSL encryption is applied to this endpoint | false | boolean1190| *sslClientCertHeaders* (security) | When enabled and in SSL mode, then the Netty consumer will enrich the Camel Message with headers having information about the client certificate such as subject name, issuer name, serial number, and the valid date range. | false | boolean1191| *sslContextParameters* (security) | To configure security using SSLContextParameters |  | SSLContextParameters1192| *sslHandler* (security) | Reference to a class that could be used to return an SSL Handler |  | SslHandler1193| *trustStoreFile* (security) | Server side certificate keystore to be used for encryption |  | File1194| *trustStoreResource* (security) | Server side certificate keystore to be used for encryption. Is loaded by default from classpath, but you can prefix with classpath:, file:, or http: to load the resource from different systems. |  | String1195|===1196// endpoint options: END1197 1198 1199 1200== Registry based Options

Showing the first 1,200 of 90013 lines. Download the file for the rest.