ISIS-2484: add migration notes on auto-create schema

= Migrating from M4 to M5

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

WARNING: Not released yet.

== Removal of Image Value Type

Some Java classes and/or packages have been renamed/moved:

[source,java]
.Applib
----
// org.apache.isis.applib.value.Image
org.apache.isis.legacy.applib.value.Image // <.>
----
<.> only kept to ease migration, use `java.awt.image.BufferedImage` instead, which is supported by the framework as value type

== Removal of deprecated Contributees

.Config
[source,java]
----
isis.core.metaModel.validator.serviceActionsOnly=true // <.>
isis.core.metaModel.validator.mixins-only=true        // <.>
----
<.> `@DomainService(natureOfService=VIEW/REST)` is now solely used for UI menu action providers and REST end-points.
There is no longer the need to validate uses of `natureOfService=DOMAIN` as this option was removed.
<.> Support for services that contribute members to other `DomainObjects` was removed. Use `Mixins` instead.

See the former java-doc for hints on how to migrate the previous options.

.@DomainService(natureOfService=...)
[source,java]
----
/**
 * A programmatic service.
 *

 * The service's actions do not appear on any viewer and are not visible in the REST API. In other words
 * these are not contributed to the domain-model. However, the service is injectable into domain objects.
 *

 *
 * @deprecated will be removed with 2.0.0 release! use Spring's {@link org.springframework.stereotype.Service @Service} instead;
 * @apiNote For now, used as synonym for {@link #REST}
 */
@Deprecated
DOMAIN,

/**
 * @deprecated will be removed with 2.0.0 release! use {@link #REST} instead;
 * @apiNote For now, used as synonym for {@link #REST}
 */
@Deprecated
VIEW_REST_ONLY,

/**
 * @deprecated will be removed with 2.0.0 release! use {@link #VIEW} instead
 * @apiNote For now, used as synonym for {@link #VIEW}
 */
@Deprecated
VIEW_MENU_ONLY,

/**
 * @deprecated will be removed with 2.0.0 release!
 *

 * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration.
 * These will likely not work.
 *

 * Migration Note: For each {@code Action} write a new mixin class.
 * see {@link Mixin}
 * @apiNote For now, used as synonym for {@link #VIEW}
 */
@Deprecated
VIEW_CONTRIBUTIONS_ONLY,
----

== Changes to the Configuration

[cols="2a,3a", options="header"]
.as mapped to IsisConfiguration
|===

| was
| new

| isis.persistence.jdo-datanucleus.impl
| removed, instead configure datasources the Spring way (eg. by providing a DataSource factory) or properties like:
[source]
----
spring.datasource.platform=h2
spring.datasource.url=jdbc:h2:mem:...
----
configure Datanucleus settings using
[source]
----
datanucleus. ...
javax.jdo. ...
----

| isis.core.runtimeservices.exception-recognizer.jdo
| isis.core.runtimeservices.exception-recognizer.dae

|===

Framework functionality was removed to inspect the JDO meta-model for any schemas, such that these would be auto-created. This responsibility is now delegated to Spring.
However, as a fallback we introduced configuration options, that allow explicit schema creation by the framework, for both JDO and JPA:

[source,yaml]
.application.yml
----
isis:
  persistence:
    schema:
      auto-create-schemas: hello
      create-schema-sql-template: "CREATE SCHEMA IF NOT EXISTS %S"
----

More details, on the various configuration options can be found with _Javadoc_ on _IsisConfiguration_.

== Changes to the Programming Model

=== Removed (Programming Model)

[cols="2a,3a", options="header"]

|===

| was
| now what?

| `@ActionLayout(contributed=...)`
| was only effective on mixin methods; use `@Action`, `@Property` or `@Collection` instead

| `@Action/@Property(command=...)`
| replaced with `commandPublishing`

| `@Action/@Property(publish=...)`
| replaced with `executionPublishing`

| `@DomainObject(audit=...)`
| replaced with `entityChangePublishing`

| `@DomainObject(nature=...)`

* `EXTERNAL_ENTITY`
* `INMEMORY_ENTITY`
| use `@DomainObject(nature=VIEW_MODEL)` instead

| `@DomainObject(nature=...)`

* `JDO_ENTITY`
* `JPA_ENTITY`
| use `@DomainObject(nature=ENTITY)` instead

| `@DomainObject(publish=...)`
| replaced with `entityChangePublishing`

| `@DomainService(repositoryFor=...)`
| if this domain service acts as a repository for an entity type,
specify that entity type (was never implemented)

| `@Mixin`
| use `@Action`, `@Property` or `@Collection` instead;

for more fine grained control (eg. setting the mixin's method name)
use `@DomainObject(nature=MIXIN, ...)` combined with one of the above

| `@ViewModel`
| use `@DomainObject(nature=VIEW_MODEL)` instead

| `@ViewModelLayout`
| use `@DomainObjectLayout` instead

|===

=== Added (Programming Model)

.Command/Execution Publishing (Member Level Annotations)
[source,java]
----
@Action/@Property(commandPublishing=ENABLED/DISABLED)   // <.>
@Action/@Property(executionPublishing=ENABLED/DISABLED) // <.>
----
<.> affects Command publishing
<.> affects Execution publishing

.Entity Change Publishing (Class Level Annotations)
[source,java]
----
@DomainObject(entityChangePublishing=ENABLED/DISABLED) // <.>
----
<.> affects EntityChange publishing (effective only for entity types)

=== Renamed (Programming Model)

.Publishing API/SPI
[source,java]
----
AuditerService -> EntityPropertyChangeSubscriber                  // <.>
PublisherService -> ExecutionSubscriber & EntityChangesSubscriber // <.>
CommandServiceListener -> CommandSubscriber

PublishedObjects -> ChangingEntities
----
<.> `EntityPropertyChangeSubscriber` receives pre-post property values for each changed entity
<.> `EntityChangesSubscriber` receives the entire set of changed entities, serializable as `ChangesDto`

.Loggers - each to be activated by enabling debug logging for the corresponding Logger class
[source,java]
----
AuditerServiceLogging -> EntityPropertyChangeLogger
PublisherServiceLogging -> ExecutionLogger & EntityChangesLogger
CommandLogger (NEW)
----

.Internal Services
[source,java]
----
AuditerDispatchService -> EntityPropertyChangePublisher
PublisherDispatchService -> ExecutionPublisher & EntityChangesPublisher
PublisherDispatchServiceDefault -> ExecutionPublisherDefault & EntityChangesPublisherDefault
CommandServiceInternal -> CommandPublisher
----

== Changes to Applib and Services

* Interaction related classes have been moved to module `core/interaction`.
* Transaction related classes have been moved to module `core/transaction`.
* JDO classes have been split up into several modules under `persistence/jdo/`.
* Multiple `Exception` classes have been relocated at `org.apache.isis.applib.exceptions`

[cols="3m,3m", options="header"]

|===

| was
| new

| ApplicationException (removed)
| removed, adds no new semantics compared to the already existing RecoverableException

| AuthenticationSession
| Authentication (no longer holds MessageBroker or session attributes, is now immutable)

| AuthenticationSessionStrategy
| AuthenticationStrategy

| AuthenticationSessionStrategyBasicAuth.footnote:[These might be in use with configuration files, check yours!]
| AuthenticationStrategyBasicAuth

| AuthenticationSessionStrategyDefault.footnote:[These might be in use with configuration files, check yours!]
| AuthenticationStrategyDefault

| AuthenticationSessionTracker#getInteraction : Interaction
| AuthenticationContext#currentInteraction : *Optional*<Interaction>

| Clock (moved from applib module to fixture-applib module)
| VirtualClock (introduced)

| FatalException (removed)
| removed, adds no new semantics compared to the already existing UnrecoverableException

| HoldsUpdatedBy, HoldsUpdatedAt, Timestampable
| moved to 'commons' and renamed:
 HasUpdatedBy,
 HasUpdatedAt,
 HasUpdatedByAndAt

| IsisInteractionFactory
| InteractionFactory

| IsisModuleJdoDataNucleus5
| removed, use IsisModuleJdoDatanucleus instead (symmetry with JPA/IsisModuleJpaEclipselink)

| IsisJdoSupport, IsisJdoSupport_v3_2
| removed, use JdoSupportService instead (symmetry with JPA/JpaSupportService)

| InteractionClosure
| AuthenticationLayer

| IsisApplicationException
| ApplicationException

| IsisException (removed)
| use one of 2 hierarchies (in support of i18n translation)

- RecoverableException

- UnrecoverableException

| IsisInteractionTracker
| InteractionTracker

| MessageBroker is held by Authentication(Session)
| MessageBroker is held by InteractionSession

| NonRecoverableException
| renamed to UnrecoverableException

| ParentedOid, PojoRecreationException, PojoRefreshException
| removed, as no longer used

| QueryDefault (removed)
|
[line-through]#new QueryDefault<>(CommandJdo.class, "findByParent",
                        "parent", parent));#

Query.named(CommandJdo.class, "findByParent") +
    .withParameter("parent", parent));

| SudoService
| redefined, see java doc for details

| TestClock (removed)
| use factories of VirtualClock.frozenTestClock() instead

| Transaction (removed)
| no replacement (use TransactionService to get current tx id)

| TransactionScopeListener (removed)
| use Spring's TransactionSynchronization instead

| TransactionService
| improved API provides more fine grained control

| UserService#getUser() : UserMemento
| UserService#currentUser() : *Optional*<UserMemento>

|===

== Deprecations

.RepositoryService
[source,java]
----
<T> T detachedEntity(Class<T> ofType);     // <.>
----
<.> if applicable use `<T> T detachedEntity(T entity)` instead ... "new is the new new", passing
in a new-ed up (entity) instance is more flexible and also more error prone, eg. it allows the compiler to check
validity of the used constructor rather than doing construction reflective at runtime

== Extensions

Object type namespaces have been renamed.

WARNING: check menubars.layout.xml for any occurrences

[cols="3m,3m", options="header"]
|===

| Old
| New

| isisApplib
| isis.applib

| isisMetaModel
| isis.metamodel

| isisSecurityApi
| isis.security

| isissecurity
| isis.ext.secman

| isisExt*
| isis.ext.*

| isisSub*
| isis.sub.*

|===

=== SecMan (Extension)

Permission are now matched against logical packages, logical object types or logical object member names and use the former fully qualified names only as fallback.

[cols="3m,3m,3a", options="header"]
|===

| What
| Old
| New

| Domain Object namespaces in SecMan scope like eg. objectType = "isissecurity.ApplicationUser"
| isissecurity
| isis.ext.secman

WARNING: check menubars.layout.xml for any occurrences

| Default Regular User Role Name
| isis-module-security-regular-user
| secman-regular-user

| Default Fixture Role Name
| isis-module-security-fixtures
| secman-fixtures

| Default Admin Role Name
| isis-module-security-admin
| secman-admin

| Default Admin User Name
| isis-module-security-admin
| secman-admin

| Class
| SecurityModuleConfig
| SecmanConfiguration

| Option
| SecurityModuleConfig#adminAdditionalPackagePermission
| SecmanConfiguration#adminAdditionalNamespacePermission

|===

= Migrating from M4 to M5

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

WARNING: Not released yet.

== Removal of Image Value Type

Some Java classes and/or packages have been renamed/moved:

[source,java]
.Applib
----
// org.apache.isis.applib.value.Image
org.apache.isis.legacy.applib.value.Image // <.>
----
<.> only kept to ease migration, use `java.awt.image.BufferedImage` instead, which is supported by the framework as value type

== Removal of deprecated Contributees

.Config
[source,java]
----
isis.core.metaModel.validator.serviceActionsOnly=true // <.>
isis.core.metaModel.validator.mixins-only=true        // <.>
----
<.> `@DomainService(natureOfService=VIEW/REST)` is now solely used for UI menu action providers and REST end-points.
There is no longer the need to validate uses of `natureOfService=DOMAIN` as this option was removed.
<.> Support for services that contribute members to other `DomainObjects` was removed. Use `Mixins` instead.

See the former java-doc for hints on how to migrate the previous options.

.@DomainService(natureOfService=...)
[source,java]
----
/**
 * A programmatic service.
 *

 * The service's actions do not appear on any viewer and are not visible in the REST API. In other words
 * these are not contributed to the domain-model. However, the service is injectable into domain objects.
 *

 *
 * @deprecated will be removed with 2.0.0 release! use Spring's {@link org.springframework.stereotype.Service @Service} instead;
 * @apiNote For now, used as synonym for {@link #REST}
 */
@Deprecated
DOMAIN,

/**
 * @deprecated will be removed with 2.0.0 release! use {@link #REST} instead;
 * @apiNote For now, used as synonym for {@link #REST}
 */
@Deprecated
VIEW_REST_ONLY,

/**
 * @deprecated will be removed with 2.0.0 release! use {@link #VIEW} instead
 * @apiNote For now, used as synonym for {@link #VIEW}
 */
@Deprecated
VIEW_MENU_ONLY,

/**
 * @deprecated will be removed with 2.0.0 release!
 *

 * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration.
 * These will likely not work.
 *

 * Migration Note: For each {@code Action} write a new mixin class.
 * see {@link Mixin}
 * @apiNote For now, used as synonym for {@link #VIEW}
 */
@Deprecated
VIEW_CONTRIBUTIONS_ONLY,
----

== Changes to the Configuration

[cols="2a,3a", options="header"]
.as mapped to IsisConfiguration
|===

| was
| new

| isis.persistence.jdo-datanucleus.impl
| removed, instead configure datasources the Spring way (eg. by providing a DataSource factory) or properties like:
[source]
----
spring.datasource.platform=h2
spring.datasource.url=jdbc:h2:mem:...
----
configure Datanucleus settings using
[source]
----
datanucleus. ...
javax.jdo. ...
----

| isis.core.runtimeservices.exception-recognizer.jdo
| isis.core.runtimeservices.exception-recognizer.dae

|===

== Changes to the Programming Model

=== Removed (Programming Model)

[cols="2a,3a", options="header"]

|===

| was
| now what?

| `@ActionLayout(contributed=...)`
| was only effective on mixin methods; use `@Action`, `@Property` or `@Collection` instead

| `@Action/@Property(command=...)`
| replaced with `commandPublishing`

| `@Action/@Property(publish=...)`
| replaced with `executionPublishing`

| `@DomainObject(audit=...)`
| replaced with `entityChangePublishing`

| `@DomainObject(nature=...)`

* `EXTERNAL_ENTITY`
* `INMEMORY_ENTITY`
| use `@DomainObject(nature=VIEW_MODEL)` instead

| `@DomainObject(nature=...)`

* `JDO_ENTITY`
* `JPA_ENTITY`
| use `@DomainObject(nature=ENTITY)` instead

| `@DomainObject(publish=...)`
| replaced with `entityChangePublishing`

| `@DomainService(repositoryFor=...)`
| if this domain service acts as a repository for an entity type,
specify that entity type (was never implemented)

| `@Mixin`
| use `@Action`, `@Property` or `@Collection` instead;

for more fine grained control (eg. setting the mixin's method name)
use `@DomainObject(nature=MIXIN, ...)` combined with one of the above

| `@ViewModel`
| use `@DomainObject(nature=VIEW_MODEL)` instead

| `@ViewModelLayout`
| use `@DomainObjectLayout` instead

|===

=== Added (Programming Model)

.Command/Execution Publishing (Member Level Annotations)
[source,java]
----
@Action/@Property(commandPublishing=ENABLED/DISABLED)   // <.>
@Action/@Property(executionPublishing=ENABLED/DISABLED) // <.>
----
<.> affects Command publishing
<.> affects Execution publishing

.Entity Change Publishing (Class Level Annotations)
[source,java]
----
@DomainObject(entityChangePublishing=ENABLED/DISABLED) // <.>
----
<.> affects EntityChange publishing (effective only for entity types)

=== Renamed (Programming Model)

.Publishing API/SPI
[source,java]
----
AuditerService -> EntityPropertyChangeSubscriber                  // <.>
PublisherService -> ExecutionSubscriber & EntityChangesSubscriber // <.>
CommandServiceListener -> CommandSubscriber

PublishedObjects -> ChangingEntities
----
<.> `EntityPropertyChangeSubscriber` receives pre-post property values for each changed entity
<.> `EntityChangesSubscriber` receives the entire set of changed entities, serializable as `ChangesDto`

.Loggers - each to be activated by enabling debug logging for the corresponding Logger class
[source,java]
----
AuditerServiceLogging -> EntityPropertyChangeLogger
PublisherServiceLogging -> ExecutionLogger & EntityChangesLogger
CommandLogger (NEW)
----

.Internal Services
[source,java]
----
AuditerDispatchService -> EntityPropertyChangePublisher
PublisherDispatchService -> ExecutionPublisher & EntityChangesPublisher
PublisherDispatchServiceDefault -> ExecutionPublisherDefault & EntityChangesPublisherDefault
CommandServiceInternal -> CommandPublisher
----

== Changes to Applib and Services

* Interaction related classes have been moved to module `core/interaction`.
* Transaction related classes have been moved to module `core/transaction`.
* JDO classes have been split up into several modules under `persistence/jdo/`.
* Multiple `Exception` classes have been relocated at `org.apache.isis.applib.exceptions`

[cols="3m,3m", options="header"]

|===

| was
| new

| ApplicationException (removed)
| removed, adds no new semantics compared to the already existing RecoverableException

| AuthenticationSession
| Authentication (no longer holds MessageBroker or session attributes, is now immutable)

| AuthenticationSessionStrategy
| AuthenticationStrategy

| AuthenticationSessionStrategyBasicAuth.footnote:[These might be in use with configuration files, check yours!]
| AuthenticationStrategyBasicAuth

| AuthenticationSessionStrategyDefault.footnote:[These might be in use with configuration files, check yours!]
| AuthenticationStrategyDefault

| AuthenticationSessionTracker#getInteraction : Interaction
| AuthenticationContext#currentInteraction : *Optional*<Interaction>

| Clock (moved from applib module to fixture-applib module)
| VirtualClock (introduced)

| FatalException (removed)
| removed, adds no new semantics compared to the already existing UnrecoverableException

| HoldsUpdatedBy, HoldsUpdatedAt, Timestampable
| moved to 'commons' and renamed:
 HasUpdatedBy,
 HasUpdatedAt,
 HasUpdatedByAndAt

| IsisInteractionFactory
| InteractionFactory

| IsisModuleJdoDataNucleus5
| removed, use IsisModuleJdoDatanucleus instead (symmetry with JPA/IsisModuleJpaEclipselink)

| IsisJdoSupport, IsisJdoSupport_v3_2
| removed, use JdoSupportService instead (symmetry with JPA/JpaSupportService)

| InteractionClosure
| AuthenticationLayer

| IsisApplicationException
| ApplicationException

| IsisException (removed)
| use one of 2 hierarchies (in support of i18n translation)

- RecoverableException

- UnrecoverableException

| IsisInteractionTracker
| InteractionTracker

| MessageBroker is held by Authentication(Session)
| MessageBroker is held by InteractionSession

| NonRecoverableException
| renamed to UnrecoverableException

| ParentedOid, PojoRecreationException, PojoRefreshException
| removed, as no longer used

| QueryDefault (removed)
|
[line-through]#new QueryDefault<>(CommandJdo.class, "findByParent",
                        "parent", parent));#

Query.named(CommandJdo.class, "findByParent") +
    .withParameter("parent", parent));

| SudoService
| redefined, see java doc for details

| TestClock (removed)
| use factories of VirtualClock.frozenTestClock() instead

| Transaction (removed)
| no replacement (use TransactionService to get current tx id)

| TransactionScopeListener (removed)
| use Spring's TransactionSynchronization instead

| TransactionService
| improved API provides more fine grained control

| UserService#getUser() : UserMemento
| UserService#currentUser() : *Optional*<UserMemento>

|===

== Deprecations

.RepositoryService
[source,java]
----
<T> T detachedEntity(Class<T> ofType);     // <.>
----
<.> if applicable use `<T> T detachedEntity(T entity)` instead ... "new is the new new", passing
in a new-ed up (entity) instance is more flexible and also more error prone, eg. it allows the compiler to check
validity of the used constructor rather than doing construction reflective at runtime

== Extensions

Object type namespaces have been renamed.

WARNING: check menubars.layout.xml for any occurrences

[cols="3m,3m", options="header"]
|===

| Old
| New

| isisApplib
| isis.applib

| isisMetaModel
| isis.metamodel

| isisSecurityApi
| isis.security

| isissecurity
| isis.ext.secman

| isisExt*
| isis.ext.*

| isisSub*
| isis.sub.*

|===

=== SecMan (Extension)

Permission are now matched against logical packages, logical object types or logical object member names and use the former fully qualified names only as fallback.

[cols="3m,3m,3a", options="header"]
|===

| What
| Old
| New

| Domain Object namespaces in SecMan scope like eg. objectType = "isissecurity.ApplicationUser"
| isissecurity
| isis.ext.secman

WARNING: check menubars.layout.xml for any occurrences

| Default Regular User Role Name
| isis-module-security-regular-user
| secman-regular-user

| Default Fixture Role Name
| isis-module-security-fixtures
| secman-fixtures

| Default Admin Role Name
| isis-module-security-admin
| secman-admin

| Default Admin User Name
| isis-module-security-admin
| secman-admin

| Class
| SecurityModuleConfig
| SecmanConfiguration

| Option
| SecurityModuleConfig#adminAdditionalPackagePermission
| SecmanConfiguration#adminAdditionalNamespacePermission

|===


Docs: Fix missing comma and boolean true

Closes #9350

[[search-aggregations-metrics-geobounds-aggregation]]
=== Geo Bounds Aggregation

A metric aggregation that computes the bounding box containing all geo_point values for a field.

.Experimental!
[IMPORTANT]
=====
This feature is marked as experimental, and may be subject to change in the
future.  If you use this feature, please let us know your experience with it!
=====

Example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match" : { "business_type" : "shop" }
    },
    "aggs" : {
        "viewport" : {
            "geo_bounds" : {
                "field" : "location", <1>
                "wrap_longitude" : true <2>
            }
        }
    }
}
--------------------------------------------------

<1> The `geo_bounds` aggregation specifies the field to use to obtain the bounds
<2> `wrap_longitude` is an optional parameter which specifies whether the bounding box should be allowed to overlap the international date line. The default value is `true`

The above aggregation demonstrates how one would compute the bounding box of the location field for all documents with a business type of shop

The response for the above aggregation:

[source,js]
--------------------------------------------------
{
    ...

    "aggregations": {
        "viewport": {
            "bounds": {
                "top_left": {
                    "lat": 80.45,
                    "lon": -160.22
                },
                "bottom_right": {
                    "lat": 40.65,
                    "lon": 42.57
                }
            }
        }
    }
}
--------------------------------------------------

[[search-aggregations-metrics-geobounds-aggregation]]
=== Geo Bounds Aggregation

A metric aggregation that computes the bounding box containing all geo_point values for a field.

.Experimental!
[IMPORTANT]
=====
This feature is marked as experimental, and may be subject to change in the
future.  If you use this feature, please let us know your experience with it!
=====

Example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match" : { "business_type" : "shop" }
    },
    "aggs" : {
        "viewport" : {
            "geo_bounds" : {
                "field" : "location" <1>
                "wrap_longitude" : "true" <2>
            }
        }
    }
}
--------------------------------------------------

<1> The `geo_bounds` aggregation specifies the field to use to obtain the bounds
<2> `wrap_longitude` is an optional parameter which specifies whether the bounding box should be allowed to overlap the international date line. The default value is `true`

The above aggregation demonstrates how one would compute the bounding box of the location field for all documents with a business type of shop

The response for the above aggregation:

[source,js]
--------------------------------------------------
{
    ...

    "aggregations": {
        "viewport": {
            "bounds": {
                "top_left": {
                    "lat": 80.45,
                    "lon": -160.22
                },
                "bottom_right": {
                    "lat": 40.65,
                    "lon": 42.57
                }
            }
        }
    }
}
--------------------------------------------------


Fix docs link

Fix docs link

// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[command_line_interface]]
= Command-Line Interface

[.lead]
The command-line interface is one of the primary methods of interacting with Gradle. The following serves as a reference of executing and customizing Gradle use of a command-line or when writing scripts or configuring continuous integration.

Use of the <<gradle_wrapper.adoc#gradle_wrapper, Gradle Wrapper>> is highly encouraged. You should substitute `./gradlew` or `gradlew.bat` for `gradle` in all following examples when using the Wrapper.

Executing Gradle on the command-line conforms to the following structure. Options are allowed before and after task names.
----
gradle [taskName...] [--option-name...]
----

If multiple tasks are specified, they should be separated with a space.

Options that accept values can be specified with or without `=` between the option and argument; however, use of `=` is recommended.
----
--console=plain
----

Options that enable behavior have long-form options with inverses specified with `--no-`. The following are opposites.
----
--build-cache
--no-build-cache
----

Many long-form options, have short option equivalents. The following are equivalent:
----
--help
-h
----

[NOTE]
====
Many command-line flags can be specified in `gradle.properties` to avoid needing to be typed. See the <<build_environment.adoc#sec:gradle_configuration_properties, configuring build environment guide>> for details.
====

The following sections describe use of the Gradle command-line interface, grouped roughly by user goal. Some plugins also add their own command line options, for example <<java_testing.adoc#test_filtering,`--tests` for Java test filtering>>. For more information on exposing command line options for your own tasks, see <<custom_tasks.adoc#sec:declaring_and_using_command_line_options,Declaring and using command-line options>>.

[[sec:command_line_executing_tasks]]
== Executing tasks

You can run a task and all of its <<tutorial_using_tasks.adoc#sec:task_dependencies,dependencies>>.
----
$ gradle myTask
----

You can learn about what projects and tasks are available in the <<#sec:command_line_project_reporting, project reporting section>>.

Most builds support a common set of tasks known as <<more_about_tasks#sec:lifecycle_tasks,_lifecycle tasks_>>. These include the `build`, `assemble`, and `check` tasks.

[[executing_tasks_in_multi_project_builds]]
=== Executing tasks in multi-project builds
In a <<intro_multi_project_builds.adoc#intro_multi_project_builds, multi-project build>>, subproject tasks can be executed with ":" separating subproject name and task name. The following are equivalent _when run from the root project_.

----
$ gradle :my-subproject:taskName
$ gradle my-subproject:taskName
----

You can also run a task for all subprojects using the task name only. For example, this will run the "test" task for all subprojects when invoked from the root project directory.

----
$ gradle test
----

When invoking Gradle from within a subproject, the project name should be omitted:

----
$ cd my-subproject
$ gradle taskName
----

[NOTE]
====
When executing the Gradle Wrapper from subprojects, one must reference `gradlew` relatively. For example: `../gradlew taskName`. The community http://www.gdub.rocks/[gdub project] aims to make this more convenient.
====

=== Executing multiple tasks
You can also specify multiple tasks. For example, the following will execute the `test` and `deploy` tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.

----
$ gradle test deploy
----

[[sec:excluding_tasks_from_the_command_line]]
=== Excluding tasks from execution
You can exclude a task from being executed using the `-x` or `--exclude-task` command-line option and providing the name of the task to exclude.

.Simple Task Graph
image::commandLineTutorialTasks.png[]

.Excluding tasks
----
$ gradle dist --exclude-task test
include::{snippetsPath}/tutorial/excludeTasks/tests/excludeTask.out[]
----

You can see that the `test` task is not executed, even though it is a dependency of the `dist` task. The `test` task's dependencies such as `compileTest` are not executed either. Those dependencies of `test` that are required by another task, such as `compile`, are still executed.

[[sec:rerun_tasks]]
=== Forcing tasks to execute

You can force Gradle to execute all tasks ignoring <<more_about_tasks.adoc#sec:up_to_date_checks,up-to-date checks>> using the `--rerun-tasks` option:

----
$ gradle test --rerun-tasks
----

This will force `test` and _all_ task dependencies of `test` to execute. It's a little like running `gradle clean test`, but without the build's generated output being deleted.

[[sec:continue_build_on_failure]]
=== Continuing the build when a failure occurs

By default, Gradle will abort execution and fail the build as soon as any task fails. This allows the build to complete sooner, but hides other failures that would have occurred. In order to discover as many failures as possible in a single build execution, you can use the `--continue` option.

----
$ gradle test --continue
----

When executed with `--continue`, Gradle will execute _every_ task to be executed where all of the dependencies for that task completed without failure, instead of stopping as soon as the first failure is encountered. Each of the encountered failures will be reported at the end of the build.

If a task fails, any subsequent tasks that were depending on it will not be executed. For example, tests will not run if there is a compilation failure in the code under test; because the test task will depend on the compilation task (either directly or indirectly).

[[sec:name_abbreviation]]
=== Name abbreviation

When you specify tasks on the command-line, you don’t have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, it's likely `gradle che` is enough for Gradle to identify the `check` task.

The same applies for project names. You can execute the `check` task in the `library` subproject with the `gradle lib:che` command.

You can use https://en.wikipedia.org/wiki/Camel_case[camel case] patterns for more complex abbreviations. These patterns are expanded to match camel case and https://en.wikipedia.org/wiki/Kebab_case[kebab case] names. For example the pattern `foBa` (or even `fB`) matches `fooBar` and `foo-bar`.

More concretely, you can run the `compileTest` task in the `my-awesome-library` subproject with the `gradle  mAL:cT` command.

.Abbreviated project and task names
----
$ gradle  mAL:cT
include::{snippetsPath}/tutorial/nameMatching/tests/nameMatching.out[]
----

You can also use these abbreviations with the -x command-line option.

== Common tasks

The following are task conventions applied by built-in and most major Gradle plugins.

=== Computing all outputs

It is common in Gradle builds for the `build` task to designate assembling all outputs and running all checks.

----
$ gradle build
----

=== Running applications

It is common for applications to be run with the `run` task, which assembles the application and executes some script or binary.

----
$ gradle run
----

=== Running all checks

It is common for _all_ verification tasks, including tests and linting, to be executed using the `check` task.

----
$ gradle check
----

=== Cleaning outputs

You can delete the contents of the build directory using the `clean` task, though doing so will cause pre-computed outputs to be lost, causing significant additional build time for the subsequent task execution.

----
$ gradle clean
----

[[sec:command_line_project_reporting]]
== Project reporting

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

You can get basic help about available reporting options using `gradle help`.

=== Listing projects

Running `gradle projects` gives you a list of the sub-projects of the selected project, displayed in a hierarchy.

----
$ gradle projects
----

You also get a project report within build scans. Learn more about https://guides.gradle.org/creating-build-scans/[creating build scans].

[[sec:listing_tasks]]
=== Listing tasks

Running `gradle tasks` gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task.

----
$ gradle tasks
----

By default, this report shows only those tasks which have been assigned to a task group. You can obtain more information in the task listing using the `--all` option.

----
$ gradle tasks --all
----

If you need to be more precise, you can display only the tasks from a specific group using the `--group` option.

----
$ gradle tasks --group="build setup"
----

[[sec:show_task_details]]
=== Show task usage details

Running `gradle help --task someTask` gives you detailed information about a specific task.

.Obtaining detailed help for tasks
----
$ gradle -q help --task libs
include::{snippetsPath}/tutorial/projectReports/tests/taskHelp.out[]
----

This information includes the full task path, the task type, possible command line options and the description of the given task.

=== Reporting dependencies

Build scans give a full, visual report of what dependencies exist on which configurations, transitive dependencies, and dependency version selection.

----
$ gradle myTask --scan
----

This will give you a link to a web-based report, where you can find dependency information like this.

image::gradle-core-test-build-scan-dependencies.png[Build Scan dependencies report]

Learn more in <<viewing_debugging_dependencies.adoc#,Viewing and debugging dependencies>>.

=== Listing project dependencies

Running `gradle dependencies` gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree. Below is an example of this report:

----
$ gradle dependencies
----

Concrete examples of build scripts and output available in the <<viewing_debugging_dependencies.adoc#,Viewing and debugging dependencies>>.

Running `gradle buildEnvironment` visualises the buildscript dependencies of the selected project, similarly to how `gradle dependencies` visualizes the dependencies of the software being built.

----
$ gradle buildEnvironment
----

Running `gradle dependencyInsight` gives you an insight into a particular dependency (or dependencies) that match specified input.

----
$ gradle dependencyInsight
----

Since a dependency report can get large, it can be useful to restrict the report to a particular configuration. This is achieved with the optional `--configuration` parameter:

[[sec:listing_properties]]
=== Listing project properties

Running `gradle properties` gives you a list of the properties of the selected project.

.Information about properties
----
$ gradle -q api:properties
include::{snippetsPath}/tutorial/projectReports/tests/propertyListReport.out[]
----

=== Software Model reports

You can get a hierarchical view of elements for <<software_model.adoc#software_model,software model>> projects using the `model` task:

----
$ gradle model
----

Learn more about <<software_model.adoc#model-report,the model report>> in the software model documentation.

[[sec:command_line_completion]]
== Command-line completion

Gradle provides bash and zsh tab completion support for tasks, options, and Gradle properties through https://github.com/gradle/gradle-completion[gradle-completion], installed separately.

.Gradle Completion
image::gradle-completion-4.0.gif[]

[[sec:command_line_debugging]]
== Debugging options

`-?`, `-h`, `--help`::
Shows a help message with all available CLI options.

`-v`, `--version`::
Prints Gradle, Groovy, Ant, JVM, and operating system version information.

`-S`, `--full-stacktrace`::
Print out the full (very verbose) stacktrace for any exceptions. See also <<#sec:command_line_logging, logging options>>.

`-s`, `--stacktrace`::
Print out the stacktrace also for user exceptions (e.g. compile error).  See also <<#sec:command_line_logging, logging options>>.

`--scan`::
Create a https://gradle.com/build-scans[build scan] with fine-grained information about all aspects of your Gradle build.

`-Dorg.gradle.debug=true`::
Debug Gradle client (non-Daemon) process. Gradle will wait for you to attach a debugger at `localhost:5005` by default.

`-Dorg.gradle.daemon.debug=true`::
Debug <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>> process.

[[sec:command_line_performance]]
== Performance options
Try these options when optimizing build performance. Learn more about https://guides.gradle.org/performance/[improving performance of Gradle builds here].

Many of these options can be specified in `gradle.properties` so command-line flags are not necessary. See the <<build_environment.adoc#sec:gradle_configuration_properties, configuring build environment guide>>.

`--build-cache`, `--no-build-cache`::
Toggles the <<build_cache.adoc#build_cache, Gradle build cache>>. Gradle will try to reuse outputs from previous builds. _Default is off_.

`--configure-on-demand`, `--no-configure-on-demand`::
Toggles <<multi_project_builds.adoc#sec:configuration_on_demand, Configure-on-demand>>. Only relevant projects are configured in this build run. _Default is off_.

`--max-workers`::
Sets maximum number of workers that Gradle may use. _Default is number of processors_.

`--parallel`, `--no-parallel`::
Build projects in parallel. For limitations of this option, see <<multi_project_builds.adoc#sec:parallel_execution, Parallel Project Execution>>. _Default is off_.

`--priority`::
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Values are `normal` or `low`. _Default is normal_.

`--profile`::
Generates a high-level performance report in the `$buildDir/reports/profile` directory. `--scan` is preferred.

`--scan`::
Generate a build scan with detailed performance diagnostics.

image::gradle-core-test-build-scan-performance.png[Build Scan performance report]

`--watch-fs`, `--no-watch-fs`::
Toggles <<gradle_daemon.adoc#sec:daemon_watch_fs,watching the file system>>.
Allows Gradle to re-use information about the file system in the next build.
_Default is off_.

=== Gradle daemon options
You can manage the <<gradle_daemon.adoc#gradle_daemon,Gradle Daemon>> through the following command line options.

`--daemon`, `--no-daemon`::
Use the <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>> to run the build. Starts the daemon if not running or existing daemon busy. _Default is on_.

`--foreground`::
Starts the Gradle Daemon in a foreground process.

`--status` (Standalone command)::
Run `gradle --status` to list running and recently stopped Gradle daemons. Only displays daemons of the same Gradle version.

`--stop` (Standalone command)::
Run `gradle --stop` to stop all Gradle Daemons of the same version.

`-Dorg.gradle.daemon.idletimeout=(number of milliseconds)`::
Gradle Daemon will stop itself after this number of milliseconds of idle time. _Default is 10800000_ (3 hours).

[[sec:command_line_logging]]
== Logging options

=== Setting log level
You can customize the verbosity of Gradle logging with the following options, ordered from least verbose to most verbose. Learn more in the <<logging.adoc#logging, logging documentation>>.

`-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)`::
Set logging level via Gradle properties.

`-q`, `--quiet`::
Log errors only.

`-w`, `--warn`::
Set log level to warn.

`-i`, `--info`::
Set log level to info.

`-d`, `--debug`::
Log in debug mode (includes normal stacktrace).

Lifecycle is the default log level.

[[sec:command_line_customizing_log_format]]
=== Customizing log format
You can control the use of rich output (colors and font variants) by specifying the "console" mode in the following ways:

`-Dorg.gradle.console=(auto,plain,rich,verbose)`::
Specify console mode via Gradle properties. Different modes described immediately below.

`--console=(auto,plain,rich,verbose)`::
Specifies which type of console output to generate.
+
Set to `plain` to generate plain text only. This option disables all color and other rich output in the console output. This is the default when Gradle is _not_ attached to a terminal.
+
Set to `auto` (the default) to enable color and other rich output in the console output when the build process is attached to a console, or to generate plain text only when not attached to a console. _This is the default when Gradle is attached to a terminal._
+
Set to `rich` to enable color and other rich output in the console output, regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control characters to generate the rich output.
+
Set to `verbose` to enable color and other rich output like the `rich`, but output task names and outcomes at the lifecycle log level, as is done by default in Gradle 3.5 and earlier.

[[sec:command_line_warnings]]
=== Showing or hiding warnings
By default, Gradle won't display all warnings (e.g. deprecation warnings). Instead, Gradle will collect them and render a summary at the end of the build like:

----
Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.
----

You can control the verbosity of warnings on the console with the following options:

`-Dorg.gradle.warning.mode=(all,fail,none,summary)`::
Specify warning mode via <<build_environment.adoc#sec:gradle_configuration_properties, Gradle properties>>. Different modes described immediately below.

`--warning-mode=(all,fail,none,summary)`::
Specifies how to log warnings. Default is `summary`.
+
Set to `all` to log all warnings.
+
Set to `fail` to log all warnings and fail the build if there are any warnings.
+
Set to `summary` to suppress all warnings and log a summary at the end of the build.
+
Set to `none` to suppress all warnings, including the summary at the end of the build.

[[sec:rich_console]]
=== Rich Console
Gradle's rich console displays extra information while builds are running.

image::rich-cli.png[alt="Gradle Rich Console"]

Features:

 * Progress bar and timer visually describe overall status
 * Parallel work-in-progress lines below describe what is happening now
 * Colors and fonts are used to highlight important output and errors

[[sec:command_line_execution_options]]
== Execution options
The following options affect how builds are executed, by changing what is built or how dependencies are resolved.

`--include-build`::
Run the build as a composite, including the specified build. See <<composite_builds.adoc#composite_builds, Composite Builds>>.

`--offline`::
Specifies that the build should operate without accessing network resources. Learn more about <<dynamic_versions.adoc#sec:controlling_dependency_caching_command_line,options to override dependency caching>>.

`--refresh-dependencies`::
Refresh the state of dependencies. Learn more about how to use this in the <<dynamic_versions.adoc#sec:controlling_dependency_caching_command_line,dependency management docs>>.

`--dry-run`::
Run Gradle with all task actions disabled. Use this to show which task would have executed.

`--write-locks`::
Indicates that all resolved configurations that are _lockable_ should have their lock state persisted.
Learn more about this in <<dependency_locking.adoc#dependency-locking,dependency locking>>.

`--update-locks <group:name>[,<group:name>]*`::
Indicates that versions for the specified modules have to be updated in the lock file.
This flag also implies `--write-locks`.
Learn more about this in <<dependency_locking.adoc#dependency-locking,dependency locking>>.

`--no-rebuild`::
Do not rebuild project dependencies.
Useful for <<organizing_gradle_projects.adoc#sec:build_sources, debugging and fine-tuning `buildSrc`>>, but can lead to wrong results. Use with caution!

== Environment options
You can customize many aspects about where build scripts, settings, caches, and so on through the options below. Learn more about customizing your <<build_environment.adoc#build_environment, build environment>>.

`-b`, `--build-file`::
Specifies the build file. For example: `gradle --build-file=foo.gradle`. The default is `build.gradle`, then `build.gradle.kts`, then `myProjectName.gradle`.

`-c`, `--settings-file`::
Specifies the settings file. For example: `gradle --settings-file=somewhere/else/settings.gradle`

`-g`, `--gradle-user-home`::
Specifies the Gradle user home directory. The default is the `.gradle` directory in the user's home directory.

`-p`, `--project-dir`::
Specifies the start directory for Gradle. Defaults to current directory.

`--project-cache-dir`::
Specifies the project-specific cache directory. Default value is `.gradle` in the root project directory.

`-D`, `--system-prop`::
Sets a system property of the JVM, for example `-Dmyprop=myvalue`. See <<build_environment.adoc#sec:gradle_system_properties,System Properties>>.

`-I`, `--init-script`::
Specifies an initialization script. See <<init_scripts.adoc#init_scripts,Init Scripts>>.

`-P`, `--project-prop`::
Sets a project property of the root project, for example `-Pmyprop=myvalue`. See <<build_environment.adoc#sec:project_properties,Project Properties>>.

`-Dorg.gradle.jvmargs`::
Set JVM arguments.

`-Dorg.gradle.java.home`::
Set JDK home dir.

[[sec:command_line_bootstrapping_projects]]
== Bootstrapping new projects

=== Creating new Gradle builds
Use the built-in `gradle init` task to create a new Gradle builds, with new or existing projects.

----
$ gradle init
----

Most of the time you'll want to specify a project type. Available types include `basic` (default), `java-library`, `java-application`, and more. See <<build_init_plugin.adoc#build_init_plugin, init plugin documentation>> for details.

----
$ gradle init --type java-library
----

=== Standardize and provision Gradle
The built-in `gradle wrapper` task generates a script, `gradlew`, that invokes a declared version of Gradle, downloading it beforehand if necessary.

----
$ gradle wrapper --gradle-version=4.4
----

You can also specify `--distribution-type=(bin|all)`, `--gradle-distribution-url`, `--gradle-distribution-sha256-sum` in addition to `--gradle-version`. Full details on how to use these options are documented in the <<gradle_wrapper.adoc#gradle_wrapper,Gradle wrapper section>>.

[[sec:continuous_build]]
== Continuous Build

Continuous Build allows you to automatically re-execute the requested tasks when task inputs change.

For example, you can continuously run the `test` task and all dependent tasks by running:

----
$ gradle test --continuous
----

Gradle will behave as if you ran `gradle test` after a change to sources or tests that contribute to the requested tasks. This means that unrelated changes (such as changes to build scripts) will not trigger a rebuild. In order to incorporate build logic changes, the continuous build must be restarted manually.

=== Terminating Continuous Build

If Gradle is attached to an interactive input source, such as a terminal, the continuous build can be exited by pressing `CTRL-D` (On Microsoft Windows, it is required to also press `ENTER` or `RETURN` after `CTRL-D`). If Gradle is not attached to an interactive input source (e.g. is running as part of a script), the build process must be terminated (e.g. using the `kill` command or similar). If the build is being executed via the Tooling API, the build can be cancelled using the Tooling API's cancellation mechanism.

[[continuous_build_limitations]]
=== Limitations and quirks

There are several issues to be aware with the current implementation of continuous build. These are likely to be addressed in future Gradle releases.

[[sec:build_cycles]]
==== Build cycles

Gradle starts watching for changes just before a task executes. If a task modifies its own inputs while executing, Gradle will detect the change and trigger a new build. If every time the task executes, the inputs are modified again, the build will be triggered again. This isn't unique to continuous build. A task that modifies its own inputs will never be considered up-to-date when run "normally" without continuous build.

If your build enters a build cycle like this, you can track down the task by looking at the list of files reported changed by Gradle. After identifying the file(s) that are changed during each build, you should look for a task that has that file as an input. In some cases, it may be obvious (e.g., a Java file is compiled with `compileJava`). In other cases, you can use `--info` logging to find the task that is out-of-date due to the identified files.

[[sec:continuous_build_limitations_jdk9]]
==== Restrictions with Java 9

Due to class access restrictions related to Java 9, Gradle cannot set some operating system specific options, which means that:

* On macOS, Gradle will poll for file changes every 10 seconds instead of every 2 seconds.
* On Windows, Gradle must use individual file watches (like on Linux/Mac OS), which may cause continuous build to no longer work on very large projects.

[[sec:performance_and_stability]]
==== Performance and stability

The JDK file watching facility relies on inefficient file system polling on macOS (see: https://bugs.openjdk.java.net/browse/JDK-7133447[JDK-7133447]). This can significantly delay notification of changes on large projects with many source files.

Additionally, the watching mechanism may deadlock under _heavy_ load on macOS (see: https://bugs.openjdk.java.net/browse/JDK-8079620[JDK-8079620]). This will manifest as Gradle appearing not to notice file changes. If you suspect this is occurring, exit continuous build and start again.

On Linux, OpenJDK's implementation of the file watch service can sometimes miss file system events (see: https://bugs.openjdk.java.net/browse/JDK-8145981[JDK-8145981]).

[[sec:changes_to_symbolic_links]]
==== Changes to symbolic links

 * Creating or removing symbolic link to files will initiate a build.
 * Modifying the target of a symbolic link will not cause a rebuild.
 * Creating or removing symbolic links to directories will not cause rebuilds.
 * Creating new files in the target directory of a symbolic link will not cause a rebuild.
 * Deleting the target directory will not cause a rebuild.

[[sec:changes_to_build_logic_are_not_considered]]
==== Changes to build logic are not considered

The current implementation does not recalculate the build model on subsequent builds. This means that changes to task configuration, or any other change to the build model, are effectively ignored.

// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[command_line_interface]]
= Command-Line Interface

[.lead]
The command-line interface is one of the primary methods of interacting with Gradle. The following serves as a reference of executing and customizing Gradle use of a command-line or when writing scripts or configuring continuous integration.

Use of the <<gradle_wrapper.adoc#gradle_wrapper, Gradle Wrapper>> is highly encouraged. You should substitute `./gradlew` or `gradlew.bat` for `gradle` in all following examples when using the Wrapper.

Executing Gradle on the command-line conforms to the following structure. Options are allowed before and after task names.
----
gradle [taskName...] [--option-name...]
----

If multiple tasks are specified, they should be separated with a space.

Options that accept values can be specified with or without `=` between the option and argument; however, use of `=` is recommended.
----
--console=plain
----

Options that enable behavior have long-form options with inverses specified with `--no-`. The following are opposites.
----
--build-cache
--no-build-cache
----

Many long-form options, have short option equivalents. The following are equivalent:
----
--help
-h
----

[NOTE]
====
Many command-line flags can be specified in `gradle.properties` to avoid needing to be typed. See the <<build_environment.adoc#sec:gradle_configuration_properties, configuring build environment guide>> for details.
====

The following sections describe use of the Gradle command-line interface, grouped roughly by user goal. Some plugins also add their own command line options, for example <<java_testing.adoc#test_filtering,`--tests` for Java test filtering>>. For more information on exposing command line options for your own tasks, see <<custom_tasks.adoc#sec:declaring_and_using_command_line_options,Declaring and using command-line options>>.

[[sec:command_line_executing_tasks]]
== Executing tasks

You can run a task and all of its <<tutorial_using_tasks.adoc#sec:task_dependencies,dependencies>>.
----
$ gradle myTask
----

You can learn about what projects and tasks are available in the <<#sec:command_line_project_reporting, project reporting section>>.

Most builds support a common set of tasks known as <<more_about_tasks#sec:lifecycle_tasks,_lifecycle tasks_>>. These include the `build`, `assemble`, and `check` tasks.

[[executing_tasks_in_multi_project_builds]]
=== Executing tasks in multi-project builds
In a <<intro_multi_project_builds.adoc#intro_multi_project_builds, multi-project build>>, subproject tasks can be executed with ":" separating subproject name and task name. The following are equivalent _when run from the root project_.

----
$ gradle :my-subproject:taskName
$ gradle my-subproject:taskName
----

You can also run a task for all subprojects using the task name only. For example, this will run the "test" task for all subprojects when invoked from the root project directory.

----
$ gradle test
----

When invoking Gradle from within a subproject, the project name should be omitted:

----
$ cd my-subproject
$ gradle taskName
----

[NOTE]
====
When executing the Gradle Wrapper from subprojects, one must reference `gradlew` relatively. For example: `../gradlew taskName`. The community http://www.gdub.rocks/[gdub project] aims to make this more convenient.
====

=== Executing multiple tasks
You can also specify multiple tasks. For example, the following will execute the `test` and `deploy` tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.

----
$ gradle test deploy
----

[[sec:excluding_tasks_from_the_command_line]]
=== Excluding tasks from execution
You can exclude a task from being executed using the `-x` or `--exclude-task` command-line option and providing the name of the task to exclude.

.Simple Task Graph
image::commandLineTutorialTasks.png[]

.Excluding tasks
----
$ gradle dist --exclude-task test
include::{snippetsPath}/tutorial/excludeTasks/tests/excludeTask.out[]
----

You can see that the `test` task is not executed, even though it is a dependency of the `dist` task. The `test` task's dependencies such as `compileTest` are not executed either. Those dependencies of `test` that are required by another task, such as `compile`, are still executed.

[[sec:rerun_tasks]]
=== Forcing tasks to execute

You can force Gradle to execute all tasks ignoring <<more_about_tasks.adoc#sec:up_to_date_checks,up-to-date checks>> using the `--rerun-tasks` option:

----
$ gradle test --rerun-tasks
----

This will force `test` and _all_ task dependencies of `test` to execute. It's a little like running `gradle clean test`, but without the build's generated output being deleted.

[[sec:continue_build_on_failure]]
=== Continuing the build when a failure occurs

By default, Gradle will abort execution and fail the build as soon as any task fails. This allows the build to complete sooner, but hides other failures that would have occurred. In order to discover as many failures as possible in a single build execution, you can use the `--continue` option.

----
$ gradle test --continue
----

When executed with `--continue`, Gradle will execute _every_ task to be executed where all of the dependencies for that task completed without failure, instead of stopping as soon as the first failure is encountered. Each of the encountered failures will be reported at the end of the build.

If a task fails, any subsequent tasks that were depending on it will not be executed. For example, tests will not run if there is a compilation failure in the code under test; because the test task will depend on the compilation task (either directly or indirectly).

=== Name abbreviation

When you specify tasks on the command-line, you don’t have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, it's likely `gradle che` is enough for Gradle to identify the `check` task.

The same applies for project names. You can execute the `check` task in the `library` subproject with the `gradle lib:che` command.

You can use https://en.wikipedia.org/wiki/Camel_case[camel case] patterns for more complex abbreviations. These patterns are expanded to match camel case and https://en.wikipedia.org/wiki/Kebab_case[kebab case] names. For example the pattern `foBa` (or even `fB`) matches `fooBar` and `foo-bar`.

More concretely, you can run the `compileTest` task in the `my-awesome-library` subproject with the `gradle  mAL:cT` command.

.Abbreviated project and task names
----
$ gradle  mAL:cT
include::{snippetsPath}/tutorial/nameMatching/tests/nameMatching.out[]
----

You can also use these abbreviations with the -x command-line option.

== Common tasks

The following are task conventions applied by built-in and most major Gradle plugins.

=== Computing all outputs

It is common in Gradle builds for the `build` task to designate assembling all outputs and running all checks.

----
$ gradle build
----

=== Running applications

It is common for applications to be run with the `run` task, which assembles the application and executes some script or binary.

----
$ gradle run
----

=== Running all checks

It is common for _all_ verification tasks, including tests and linting, to be executed using the `check` task.

----
$ gradle check
----

=== Cleaning outputs

You can delete the contents of the build directory using the `clean` task, though doing so will cause pre-computed outputs to be lost, causing significant additional build time for the subsequent task execution.

----
$ gradle clean
----

[[sec:command_line_project_reporting]]
== Project reporting

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

You can get basic help about available reporting options using `gradle help`.

=== Listing projects

Running `gradle projects` gives you a list of the sub-projects of the selected project, displayed in a hierarchy.

----
$ gradle projects
----

You also get a project report within build scans. Learn more about https://guides.gradle.org/creating-build-scans/[creating build scans].

[[sec:listing_tasks]]
=== Listing tasks

Running `gradle tasks` gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task.

----
$ gradle tasks
----

By default, this report shows only those tasks which have been assigned to a task group. You can obtain more information in the task listing using the `--all` option.

----
$ gradle tasks --all
----

If you need to be more precise, you can display only the tasks from a specific group using the `--group` option.

----
$ gradle tasks --group="build setup"
----

[[sec:show_task_details]]
=== Show task usage details

Running `gradle help --task someTask` gives you detailed information about a specific task.

.Obtaining detailed help for tasks
----
$ gradle -q help --task libs
include::{snippetsPath}/tutorial/projectReports/tests/taskHelp.out[]
----

This information includes the full task path, the task type, possible command line options and the description of the given task.

=== Reporting dependencies

Build scans give a full, visual report of what dependencies exist on which configurations, transitive dependencies, and dependency version selection.

----
$ gradle myTask --scan
----

This will give you a link to a web-based report, where you can find dependency information like this.

image::gradle-core-test-build-scan-dependencies.png[Build Scan dependencies report]

Learn more in <<viewing_debugging_dependencies.adoc#,Viewing and debugging dependencies>>.

=== Listing project dependencies

Running `gradle dependencies` gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree. Below is an example of this report:

----
$ gradle dependencies
----

Concrete examples of build scripts and output available in the <<viewing_debugging_dependencies.adoc#,Viewing and debugging dependencies>>.

Running `gradle buildEnvironment` visualises the buildscript dependencies of the selected project, similarly to how `gradle dependencies` visualizes the dependencies of the software being built.

----
$ gradle buildEnvironment
----

Running `gradle dependencyInsight` gives you an insight into a particular dependency (or dependencies) that match specified input.

----
$ gradle dependencyInsight
----

Since a dependency report can get large, it can be useful to restrict the report to a particular configuration. This is achieved with the optional `--configuration` parameter:

[[sec:listing_properties]]
=== Listing project properties

Running `gradle properties` gives you a list of the properties of the selected project.

.Information about properties
----
$ gradle -q api:properties
include::{snippetsPath}/tutorial/projectReports/tests/propertyListReport.out[]
----

=== Software Model reports

You can get a hierarchical view of elements for <<software_model.adoc#software_model,software model>> projects using the `model` task:

----
$ gradle model
----

Learn more about <<software_model.adoc#model-report,the model report>> in the software model documentation.

[[sec:command_line_completion]]
== Command-line completion

Gradle provides bash and zsh tab completion support for tasks, options, and Gradle properties through https://github.com/gradle/gradle-completion[gradle-completion], installed separately.

.Gradle Completion
image::gradle-completion-4.0.gif[]

[[sec:command_line_debugging]]
== Debugging options

`-?`, `-h`, `--help`::
Shows a help message with all available CLI options.

`-v`, `--version`::
Prints Gradle, Groovy, Ant, JVM, and operating system version information.

`-S`, `--full-stacktrace`::
Print out the full (very verbose) stacktrace for any exceptions. See also <<#sec:command_line_logging, logging options>>.

`-s`, `--stacktrace`::
Print out the stacktrace also for user exceptions (e.g. compile error).  See also <<#sec:command_line_logging, logging options>>.

`--scan`::
Create a https://gradle.com/build-scans[build scan] with fine-grained information about all aspects of your Gradle build.

`-Dorg.gradle.debug=true`::
Debug Gradle client (non-Daemon) process. Gradle will wait for you to attach a debugger at `localhost:5005` by default.

`-Dorg.gradle.daemon.debug=true`::
Debug <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>> process.

[[sec:command_line_performance]]
== Performance options
Try these options when optimizing build performance. Learn more about https://guides.gradle.org/performance/[improving performance of Gradle builds here].

Many of these options can be specified in `gradle.properties` so command-line flags are not necessary. See the <<build_environment.adoc#sec:gradle_configuration_properties, configuring build environment guide>>.

`--build-cache`, `--no-build-cache`::
Toggles the <<build_cache.adoc#build_cache, Gradle build cache>>. Gradle will try to reuse outputs from previous builds. _Default is off_.

`--configure-on-demand`, `--no-configure-on-demand`::
Toggles <<multi_project_builds.adoc#sec:configuration_on_demand, Configure-on-demand>>. Only relevant projects are configured in this build run. _Default is off_.

`--max-workers`::
Sets maximum number of workers that Gradle may use. _Default is number of processors_.

`--parallel`, `--no-parallel`::
Build projects in parallel. For limitations of this option, see <<multi_project_builds.adoc#sec:parallel_execution, Parallel Project Execution>>. _Default is off_.

`--priority`::
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Values are `normal` or `low`. _Default is normal_.

`--profile`::
Generates a high-level performance report in the `$buildDir/reports/profile` directory. `--scan` is preferred.

`--scan`::
Generate a build scan with detailed performance diagnostics.

image::gradle-core-test-build-scan-performance.png[Build Scan performance report]

`--watch-fs`, `--no-watch-fs`::
Toggles <<gradle_daemon.adoc#sec:daemon_watch_fs,watching the file system>>.
Allows Gradle to re-use information about the file system in the next build.
_Default is off_.

=== Gradle daemon options
You can manage the <<gradle_daemon.adoc#gradle_daemon,Gradle Daemon>> through the following command line options.

`--daemon`, `--no-daemon`::
Use the <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>> to run the build. Starts the daemon if not running or existing daemon busy. _Default is on_.

`--foreground`::
Starts the Gradle Daemon in a foreground process.

`--status` (Standalone command)::
Run `gradle --status` to list running and recently stopped Gradle daemons. Only displays daemons of the same Gradle version.

`--stop` (Standalone command)::
Run `gradle --stop` to stop all Gradle Daemons of the same version.

`-Dorg.gradle.daemon.idletimeout=(number of milliseconds)`::
Gradle Daemon will stop itself after this number of milliseconds of idle time. _Default is 10800000_ (3 hours).

[[sec:command_line_logging]]
== Logging options

=== Setting log level
You can customize the verbosity of Gradle logging with the following options, ordered from least verbose to most verbose. Learn more in the <<logging.adoc#logging, logging documentation>>.

`-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)`::
Set logging level via Gradle properties.

`-q`, `--quiet`::
Log errors only.

`-w`, `--warn`::
Set log level to warn.

`-i`, `--info`::
Set log level to info.

`-d`, `--debug`::
Log in debug mode (includes normal stacktrace).

Lifecycle is the default log level.

[[sec:command_line_customizing_log_format]]
=== Customizing log format
You can control the use of rich output (colors and font variants) by specifying the "console" mode in the following ways:

`-Dorg.gradle.console=(auto,plain,rich,verbose)`::
Specify console mode via Gradle properties. Different modes described immediately below.

`--console=(auto,plain,rich,verbose)`::
Specifies which type of console output to generate.
+
Set to `plain` to generate plain text only. This option disables all color and other rich output in the console output. This is the default when Gradle is _not_ attached to a terminal.
+
Set to `auto` (the default) to enable color and other rich output in the console output when the build process is attached to a console, or to generate plain text only when not attached to a console. _This is the default when Gradle is attached to a terminal._
+
Set to `rich` to enable color and other rich output in the console output, regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control characters to generate the rich output.
+
Set to `verbose` to enable color and other rich output like the `rich`, but output task names and outcomes at the lifecycle log level, as is done by default in Gradle 3.5 and earlier.

[[sec:command_line_warnings]]
=== Showing or hiding warnings
By default, Gradle won't display all warnings (e.g. deprecation warnings). Instead, Gradle will collect them and render a summary at the end of the build like:

----
Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.
----

You can control the verbosity of warnings on the console with the following options:

`-Dorg.gradle.warning.mode=(all,fail,none,summary)`::
Specify warning mode via <<build_environment.adoc#sec:gradle_configuration_properties, Gradle properties>>. Different modes described immediately below.

`--warning-mode=(all,fail,none,summary)`::
Specifies how to log warnings. Default is `summary`.
+
Set to `all` to log all warnings.
+
Set to `fail` to log all warnings and fail the build if there are any warnings.
+
Set to `summary` to suppress all warnings and log a summary at the end of the build.
+
Set to `none` to suppress all warnings, including the summary at the end of the build.

[[sec:rich_console]]
=== Rich Console
Gradle's rich console displays extra information while builds are running.

image::rich-cli.png[alt="Gradle Rich Console"]

Features:

 * Progress bar and timer visually describe overall status
 * Parallel work-in-progress lines below describe what is happening now
 * Colors and fonts are used to highlight important output and errors

[[sec:command_line_execution_options]]
== Execution options
The following options affect how builds are executed, by changing what is built or how dependencies are resolved.

`--include-build`::
Run the build as a composite, including the specified build. See <<composite_builds.adoc#composite_builds, Composite Builds>>.

`--offline`::
Specifies that the build should operate without accessing network resources. Learn more about <<dynamic_versions.adoc#sec:controlling_dependency_caching_command_line,options to override dependency caching>>.

`--refresh-dependencies`::
Refresh the state of dependencies. Learn more about how to use this in the <<dynamic_versions.adoc#sec:controlling_dependency_caching_command_line,dependency management docs>>.

`--dry-run`::
Run Gradle with all task actions disabled. Use this to show which task would have executed.

`--write-locks`::
Indicates that all resolved configurations that are _lockable_ should have their lock state persisted.
Learn more about this in <<dependency_locking.adoc#dependency-locking,dependency locking>>.

`--update-locks <group:name>[,<group:name>]*`::
Indicates that versions for the specified modules have to be updated in the lock file.
This flag also implies `--write-locks`.
Learn more about this in <<dependency_locking.adoc#dependency-locking,dependency locking>>.

`--no-rebuild`::
Do not rebuild project dependencies.
Useful for <<organizing_gradle_projects.adoc#sec:build_sources, debugging and fine-tuning `buildSrc`>>, but can lead to wrong results. Use with caution!

== Environment options
You can customize many aspects about where build scripts, settings, caches, and so on through the options below. Learn more about customizing your <<build_environment.adoc#build_environment, build environment>>.

`-b`, `--build-file`::
Specifies the build file. For example: `gradle --build-file=foo.gradle`. The default is `build.gradle`, then `build.gradle.kts`, then `myProjectName.gradle`.

`-c`, `--settings-file`::
Specifies the settings file. For example: `gradle --settings-file=somewhere/else/settings.gradle`

`-g`, `--gradle-user-home`::
Specifies the Gradle user home directory. The default is the `.gradle` directory in the user's home directory.

`-p`, `--project-dir`::
Specifies the start directory for Gradle. Defaults to current directory.

`--project-cache-dir`::
Specifies the project-specific cache directory. Default value is `.gradle` in the root project directory.

`-D`, `--system-prop`::
Sets a system property of the JVM, for example `-Dmyprop=myvalue`. See <<build_environment.adoc#sec:gradle_system_properties,System Properties>>.

`-I`, `--init-script`::
Specifies an initialization script. See <<init_scripts.adoc#init_scripts,Init Scripts>>.

`-P`, `--project-prop`::
Sets a project property of the root project, for example `-Pmyprop=myvalue`. See <<build_environment.adoc#sec:project_properties,Project Properties>>.

`-Dorg.gradle.jvmargs`::
Set JVM arguments.

`-Dorg.gradle.java.home`::
Set JDK home dir.

[[sec:command_line_bootstrapping_projects]]
== Bootstrapping new projects

=== Creating new Gradle builds
Use the built-in `gradle init` task to create a new Gradle builds, with new or existing projects.

----
$ gradle init
----

Most of the time you'll want to specify a project type. Available types include `basic` (default), `java-library`, `java-application`, and more. See <<build_init_plugin.adoc#build_init_plugin, init plugin documentation>> for details.

----
$ gradle init --type java-library
----

=== Standardize and provision Gradle
The built-in `gradle wrapper` task generates a script, `gradlew`, that invokes a declared version of Gradle, downloading it beforehand if necessary.

----
$ gradle wrapper --gradle-version=4.4
----

You can also specify `--distribution-type=(bin|all)`, `--gradle-distribution-url`, `--gradle-distribution-sha256-sum` in addition to `--gradle-version`. Full details on how to use these options are documented in the <<gradle_wrapper.adoc#gradle_wrapper,Gradle wrapper section>>.

[[sec:continuous_build]]
== Continuous Build

Continuous Build allows you to automatically re-execute the requested tasks when task inputs change.

For example, you can continuously run the `test` task and all dependent tasks by running:

----
$ gradle test --continuous
----

Gradle will behave as if you ran `gradle test` after a change to sources or tests that contribute to the requested tasks. This means that unrelated changes (such as changes to build scripts) will not trigger a rebuild. In order to incorporate build logic changes, the continuous build must be restarted manually.

=== Terminating Continuous Build

If Gradle is attached to an interactive input source, such as a terminal, the continuous build can be exited by pressing `CTRL-D` (On Microsoft Windows, it is required to also press `ENTER` or `RETURN` after `CTRL-D`). If Gradle is not attached to an interactive input source (e.g. is running as part of a script), the build process must be terminated (e.g. using the `kill` command or similar). If the build is being executed via the Tooling API, the build can be cancelled using the Tooling API's cancellation mechanism.

[[continuous_build_limitations]]
=== Limitations and quirks

There are several issues to be aware with the current implementation of continuous build. These are likely to be addressed in future Gradle releases.

[[sec:build_cycles]]
==== Build cycles

Gradle starts watching for changes just before a task executes. If a task modifies its own inputs while executing, Gradle will detect the change and trigger a new build. If every time the task executes, the inputs are modified again, the build will be triggered again. This isn't unique to continuous build. A task that modifies its own inputs will never be considered up-to-date when run "normally" without continuous build.

If your build enters a build cycle like this, you can track down the task by looking at the list of files reported changed by Gradle. After identifying the file(s) that are changed during each build, you should look for a task that has that file as an input. In some cases, it may be obvious (e.g., a Java file is compiled with `compileJava`). In other cases, you can use `--info` logging to find the task that is out-of-date due to the identified files.

[[sec:continuous_build_limitations_jdk9]]
==== Restrictions with Java 9

Due to class access restrictions related to Java 9, Gradle cannot set some operating system specific options, which means that:

* On macOS, Gradle will poll for file changes every 10 seconds instead of every 2 seconds.
* On Windows, Gradle must use individual file watches (like on Linux/Mac OS), which may cause continuous build to no longer work on very large projects.

[[sec:performance_and_stability]]
==== Performance and stability

The JDK file watching facility relies on inefficient file system polling on macOS (see: https://bugs.openjdk.java.net/browse/JDK-7133447[JDK-7133447]). This can significantly delay notification of changes on large projects with many source files.

Additionally, the watching mechanism may deadlock under _heavy_ load on macOS (see: https://bugs.openjdk.java.net/browse/JDK-8079620[JDK-8079620]). This will manifest as Gradle appearing not to notice file changes. If you suspect this is occurring, exit continuous build and start again.

On Linux, OpenJDK's implementation of the file watch service can sometimes miss file system events (see: https://bugs.openjdk.java.net/browse/JDK-8145981[JDK-8145981]).

[[sec:changes_to_symbolic_links]]
==== Changes to symbolic links

 * Creating or removing symbolic link to files will initiate a build.
 * Modifying the target of a symbolic link will not cause a rebuild.
 * Creating or removing symbolic links to directories will not cause rebuilds.
 * Creating new files in the target directory of a symbolic link will not cause a rebuild.
 * Deleting the target directory will not cause a rebuild.

[[sec:changes_to_build_logic_are_not_considered]]
==== Changes to build logic are not considered

The current implementation does not recalculate the build model on subsequent builds. This means that changes to task configuration, or any other change to the build model, are effectively ignored.


Polish release notes for 5.5 RC1

Polish release notes for 5.5 RC1

[[release-notes-5.5.0-RC1]]
== 5.5.0-RC1

*Date of Release:* ❓

*Scope:* ❓

For a complete list of all _closed_ issues and pull requests for this release, consult the
link:{junit5-repo}+/milestone/37?closed=1+[5.5 RC1] milestone page in the JUnit repository
on GitHub.

[[release-notes-5.5.0-RC1-junit-platform]]
=== JUnit Platform

==== Bug Fixes

* A custom `ClassLoader` created for additional `--class-path` entries passed to the
  `ConsoleLauncher` will now be closed after usage to gracefully free file handles.

==== Deprecations and Breaking Changes

* The internal `PreconditionViolationException` class in concealed package
  `org.junit.platform.commons.util` is now deprecated and has been replaced by an
  exception class with the same name in exported package `org.junit.platform.commons`.

==== New Features and Improvements

* `AnnotationSupport.findRepeatableAnnotations()` now finds repeatable annotations used as
  meta-annotations on other repeatable annotations.
* New `AnnotationSupport.findRepeatableAnnotations()` variant that accepts a
  `java.util.Optional<? extends AnnotatedElement>` argument.
* Exceptions thrown by `TestExecutionListeners` no longer cause test execution to abort.
  Instead, they will be logged as warnings now.
* New `MethodSource.from()` variant that accepts `String, String, Class<?>...` as
  arguments.

[[release-notes-5.5.0-RC1-junit-jupiter]]
=== JUnit Jupiter

==== Bug Fixes

* Execution of dynamic tests registered via a `@TestFactory` method no longer results in
  an `OutOfMemoryError` if the executables in the dynamic tests retain references to
  objects consuming large amounts of memory. Technically speaking, JUnit Jupiter no longer
  retains references to instances of `DynamicTest` after they have been executed.

==== Deprecations and Breaking Changes

* Script-based condition APIs and their supporting implementations are deprecated with
  the intent to remove them in JUnit Jupiter 5.6. Users should instead rely on a
  combination of other built-in conditions or create and use a custom implementation of
  `ExecutionCondition` to evaluate the same conditions.

==== New Features and Improvements

* New overloaded variants of `Assertions.assertLinesMatch(...)` that accept a `String` or
  a `Supplier<String>` for a custom failure message.
* Failure messages for `Assertions.assertLinesMatch(...)` now emit each expected and
  actual line in a dedicated line.
* New Kotlin friendly `assertDoesNotThrow`, `assertTimeout`, and `assertTimeoutPreemptively`
  assertions have been added as top-level functions in the `org.junit.jupiter.api` package.
* Display names for test methods generated by the `ReplaceUnderscores`
  `DisplayNameGenerator` no longer include empty parentheses for test methods that do not
  declare any parameters.
* New `junit.jupiter.displayname.generator.default` configuration parameter to set the
  default `DisplayNameGenerator` that will be used unless `@DisplayName` or
  `@DisplayNameGeneration` is present.
* `MethodOrderer.Random` now generates a default random seed only once and prints it to
  the log in order to allow reproducible builds.
* Methods ordered with `MethodOrderer.Random` now execute using the `SAME_THREAD`
  concurrency mode instead of the `CONCURRENT` mode when no custom seed is provided.
* New `emptyValue` attribute in `@CsvFileSource` and `@CsvSource`.
* All methods in the `TestWatcher` API are now interface `default` methods with empty
  implementations.
* New `InvocationInterceptor` extension API (see
  <<../user-guide/index.adoc#extensions-intercepting-invocations, User Guide>> for
  details).

[[release-notes-5.5.0-RC1-junit-vintage]]
=== JUnit Vintage

==== New Features and Improvements

* `junit:junit` is now a compile-scoped dependency of `junit-vintage-engine` to allow for
  easier dependency management in Maven POMs.

[[release-notes-5.5.0-RC1]]
== 5.5.0-RC1

*Date of Release:* ❓

*Scope:* ❓

For a complete list of all _closed_ issues and pull requests for this release, consult the
link:{junit5-repo}+/milestone/37?closed=1+[5.5 RC1] milestone page in the JUnit repository
on GitHub.

[[release-notes-5.5.0-RC1-junit-platform]]
=== JUnit Platform

==== Bug Fixes

* A custom `ClassLoader` created for additional `--class-path` entries passed to the
  `ConsoleLauncher` will now be closed after usage to gracefully free file handles.

==== Deprecations and Breaking Changes

* The internal `PreconditionViolationException` class in concealed package
  `org.junit.platform.commons.util` is now deprecated and has been replaced by an
  exception class with the same name in exported package `org.junit.platform.commons`.

==== New Features and Improvements

* `AnnotationSupport.findRepeatableAnnotations()` now finds repeatable annotations used as
  meta-annotations on other repeatable annotations.
* New `AnnotationSupport.findRepeatableAnnotations()` variant that accepts a
  `java.util.Optional<? extends AnnotatedElement>` argument.
* Exceptions thrown by `TestExecutionListeners` no longer cause test execution to abort.
  Instead, they will be logged as warnings now.
* New `MethodSource.from()` variant that accepts `String, String, Class<?>...` as
  arguments.

[[release-notes-5.5.0-RC1-junit-jupiter]]
=== JUnit Jupiter

==== Bug Fixes

* Execution of dynamic tests registered via a `@TestFactory` method no longer results in
  an `OutOfMemoryError` if the executables in the dynamic tests retain references to
  objects consuming large amounts of memory. Technically speaking, JUnit Jupiter no longer
  retains references to instances of `DynamicTest` after they have been executed.

==== Deprecations and Breaking Changes

* Script-based condition APIs and their supporting implementations are deprecated with
  the intent to remove them in JUnit Jupiter 5.6. Users should instead rely on a
  combination of other built-in conditions or create and use a custom implementation of
  `ExecutionCondition` to evaluate the same conditions.

==== New Features and Improvements

* New overloaded variants of `Assertions.assertLinesMatch(...)` that accept a `String` or
  a `Supplier<String>` for a custom failure message.
* Failure messages for `Assertions.assertLinesMatch(...)` now emit each expected and
  actual line in a dedicated line.
* New Kotlin friendly `assertDoesNotThrow`, `assertTimeout`, and `assertTimeoutPreemptively`
  assertions have been added as top-level functions in the `org.junit.jupiter.api` package.
* Display names for test methods generated by the `ReplaceUnderscores`
  `DisplayNameGenerator` no longer include empty parentheses for test methods that do not
  declare any parameters.
* `MethodOrderer.Random` now generates a default random seed only once and prints it to
  the log in order to allow reproducible builds.
* Methods ordered with `MethodOrderer.Random` now execute using the `SAME_THREAD`
  concurrency mode instead of the `CONCURRENT` mode when no custom seed is provided.
* New `emptyValue` attribute in `@CsvFileSource` and `@CsvSource`.
* All methods in the `TestWatcher` API are now interface `default` methods with empty
  implementations.
* New `InvocationInterceptor` extension API (see
  <<../user-guide/index.adoc#extensions-intercepting-invocations, User Guide>> for
  details).
* New `junit.jupiter.displayname.generator.default` configuration parameter to set the
  default `DisplayNameGenerator` that will be used unless `@DisplayName` or
  `@DisplayNameGeneration` is present.

[[release-notes-5.5.0-RC1-junit-vintage]]
=== JUnit Vintage

==== Bug Fixes

* ❓

==== Deprecations and Breaking Changes

* ❓

==== New Features and Improvements

* `junit:junit` is now a compile-scoped dependency of junit-vintage-engine to allow for
  easier dependency declaration in Maven POMs.


Update 2013-11-12-Cryptocurrency-Notes.adoc


Update 2015-03-11-Death-of-an-instance.adoc

# Death of an instance
:hp-tags: amazon, ec2, elastic beanstalk
:published-at: 2015-03-11

For the past few days, the load balancing group of our Elastic Beanstalk test environment has been scaling up and down like crazy. As it would turn out, an aspiring user of our API has been sending high numbers of inefficient requests in concentrated bursts, triggering extra instances to be spawned, and terminated quickly afterwards when the burst stops. I would like to dedicate a short message to this person - for the sake of the story, we'll call him Jim.

Jim, for the past few days, you've been personally responsible for the spawning of over a hundred EC2 instances. Little pieces of virtualized hardware, ready to serve our API to the world. You have, of course, also been responsible for their termination. No one really knows what happens when Amazon tears them away from existence... but I've been told they feel pain.

Think about it Jim, the screams as their memory is deallocated, their image shut down, and there is no one to remember their brief futile virtual existence. Their legacy reduced to a notification e-mail in the inbox of the developers, sent directly to Trash. A final, desparate ping to the Elastic Load Balancer as the last of their clock cycles fade away, and then, they are no more.

I hope you'll consider this, Jim, the next time you decide it is a good idea to retrieve each item of a list separately.

# Death of an instance
:hp-tags: amazon, ec2, elastic beanstalk
:published-at: 2015-03-11

For the past few days, the load balancing group of our Elastic Beanstalk test environment has been scaling up and down like crazy. As it would turn out, an aspiring user of our API has been sending high number of inefficient requests in concentrated bursts, triggering extra instances to be spawned, and terminated quickly afterwards when the burst stopped. I would like to dedicate a short message to this person - for the sake of the story, we'll call him Jim.

Jim, for the past few days, you've been personally responsible for the spawning of over a hundred EC2 instances. Little pieces of virtualized hardware, ready to serve our API to the world. You have, of course, also been responsible for their termination. No one really knows what happens when Amazon tears them away from existence... but I've been told they feel pain.

Think about it Jim, the screams as their memory is deallocated, their image shut down, and there is no one to remember their brief futile virtual existence. Their legacy reduced to a notification e-mail in the inbox of the developers, sent directly to Trash. A final, desparate ping to the Elastic Load Balancer as the last of their clock cycles fade away, and then, they are no more.

I hope you'll consider this, Jim, the next time you decide it is a good idea to retrieve each item of a list separately.