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

     https://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.
////

= cache

*Tag:* cache

[*__since 2.0__*]

[ivysettings.caches.cache]#Defines a repository cache instance based on the default repository cache implementation.#

The default repository cache implementation caches files on the local filesystem in subdirectories of a configured base directory.

By default also, the parsed module descriptors read from the cache are kept in a memory cache in case they are reused. This may enhance the performance of multi-module build, provided that all modules are built using the same Ivy instance. The size of this memory cache is configurable in terms of number of module descriptors. A size of 0 means no memory caching.


== Attributes


[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|name|name of the cache instance|Yes
|basedir|the path of the base directory to use to put repository cache data. *This should not point to a directory used as a repository!*|No, defaults to repositoryCacheDir defined in link:../../settings/caches{outfilesuffix}[caches]
|ivyPattern|the pattern to use to store cached Ivy files|No, defaults to default cache Ivy pattern as configured in link:../../settings/caches{outfilesuffix}[caches]
|artifactPattern|the pattern to use to store cached artifacts|No, defaults to default cache artifact pattern as configured in link:../../settings/caches{outfilesuffix}[caches]
|useOrigin|true to avoid the copy of local artifacts to the cache and use directly their original location, false otherwise.
To know if an artifact is local, Ivy asks the resolver. Only filesystem resolver is considered local by default, but this can be disabled if you want to force the copy on one filesystem resolver and use the original location on another. Note that it is safe to use useOrigin even if you use the cache for some non local resolvers. In this case the cache will behave as usual, copying files to the cache. Note also that this only applies to artifacts, not to Ivy files, which are still copied in the cache.|No. defaults to the default value configured in link:../../settings/caches{outfilesuffix}[caches]
|lockStrategy|the name of the link:../../settings/lock-strategies{outfilesuffix}[lock strategy] to use for this cache|No, defaults to default lock strategy as configured in link:../../settings/caches{outfilesuffix}[caches]
|defaultTTL|the default link:../../settings/caches/ttl{outfilesuffix}[TTL] to use when no specific one is defined|No, defaults to ${ivy.cache.ttl.default}
|memorySize|the number of parsed module descriptors to keep in a memory cache.|No, default to 150
|=======



== Child elements


[options="header"]
|=======
|Element|Description|Cardinality
|link:../../settings/caches/ttl{outfilesuffix}[ttl]|defines a TTL rule|0..n
|=======



== Examples


[source, xml]
----

<cache name="mycache"
       basedir="/path/to/mycache"
       ivyPattern="[module]/ivy-[revision].xml"
       artifactPattern="[module]/[artifact]-[revision].[ext]"
       lockStrategy="no-lock"
       defaultTTL="1s">
    <ttl revision="latest.integration" duration="200ms"/>
    <ttl organisation="org1" duration="10m 20s"/>
    <ttl organisation="org2" duration="5h"/>
    <ttl organisation="org3" duration="2d 12h"/>
</cache>

----

Defines a cache called `mycache`, storing files in the `/path/to/mycache` directory using `[module]/ivy-[revision].xml` as a pattern to store Ivy files and `[module]/[artifact]-[revision].[ext]` as a pattern to store other artifacts. The lock strategy used by this cache is the `no-lock` strategy, which does not perform any locking. The defaultTTL used is 1 s, meaning that by default dynamic revision result will be stored and used for one second. TTL rules then define that all `latest.integration` revisions will be stored and used for 200 ms, while other dynamic revisions from `org1` `org2` and `org3` modules will be stored respectively for 10 minutes 20 seconds; 5 hours; and 2 days and 12 hours.
