Author: xavier
Date: Sun Dec 2 07:56:22 2007
New Revision: 600318
URL: http://svn.apache.org/viewvc?rev=600318&view=rev
Log:
document new cache settings (IVY-628 and IVY-654)
Added:
incubator/ivy/core/trunk/doc/configuration/cache.html (with props)
incubator/ivy/core/trunk/doc/configuration/lock-strategies.html (with
props)
Modified:
incubator/ivy/core/trunk/doc/configuration.html
incubator/ivy/core/trunk/doc/configuration/conf.html
incubator/ivy/core/trunk/doc/extend.html
incubator/ivy/core/trunk/doc/toc.json
Modified: incubator/ivy/core/trunk/doc/configuration.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/configuration.html?rev=600318&r1=600317&r2=600318&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/configuration.html (original)
+++ incubator/ivy/core/trunk/doc/configuration.html Sun Dec 2 07:56:22 2007
@@ -25,16 +25,16 @@
</head>
<body>
<textarea id="xooki-source">
-In order to work as you want, ivy sometimes need some settings. Actually, ivy
can work with no specific settings at all, see the <a
href="tutorial/defaultconf.html">default settings documentation</a> for details
about that. But ivy is able
-to work in very different contexts. You just have to configure it properly.
+In order to work as you want, ivy sometimes need some settings. Actually, ivy
can work with no specific settings at all, see the <a
href="tutorial/defaultconf.html">default settings documentation</a> for details
about that. But ivy is able to work in very different contexts. You just have
to configure it properly.
-Settings are specified through an xml file, usually called ivysettings.xml. To
configure ivy from ant, you just have to call the configure task and pass it
the path to your settings file (see <a href="use/configure.html">configure</a>
task documentation for details).
+Settings are specified through an xml file, usually called ivysettings.xml. To
configure ivy from ant, you just have to use the [[ant:settings]] datatype with
the path of your settings file.
Here is an example of settings file :
<code type="xml">
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings-file.properties" />
- <settings defaultCache="${cache.dir}" defaultResolver="ibiblio"
checkUpToDate="false" />
+ <settings defaultResolver="ibiblio" checkUpToDate="false" />
+ <cache basedir="${cache.dir}" />
<resolvers>
<ibiblio name="ibiblio" />
<filesystem name="internal">
@@ -73,6 +73,8 @@
<a href="configuration/include.html">include</a>
<a href="configuration/classpath.html">classpath</a>
<a href="configuration/typedef.html">typedef</a>
+ <a href="configuration/lock-strategies.html">lock-strategies</a>
+ <a href="configuration/cache.html">cache</a>
<a href="configuration/latest-strategies.html">latest-strategies</a>
<a href="configuration/version-matchers.html">version-matchers</a>
<a href="configuration/triggers.html">triggers</a>
@@ -121,6 +123,10 @@
<td>0..n</td></tr>
<tr><td><a href="configuration/typedef.html">typedef</a></td><td>defines
new types in ivy</td>
<td>0..n</td></tr>
+ <tr><td><a
href="configuration/lock-strategies.html">lock-strategies</a></td><td>defines
lock strategies</td>
+ <td>0..1</td></tr>
+ <tr><td><a href="configuration/cache.html">cache</a></td><td>set up the
cache</td>
+ <td>0..1</td></tr>
<tr><td><a
href="configuration/latest-strategies.html">latest-strategies</a></td><td>defines
latest strategies</td>
<td>0..1</td></tr>
<tr><td><a href="configuration/parsers.html">parsers</a></td><td>defines
module descriptor parsers</td>
Added: incubator/ivy/core/trunk/doc/configuration/cache.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/configuration/cache.html?rev=600318&view=auto
==============================================================================
--- incubator/ivy/core/trunk/doc/configuration/cache.html (added)
+++ incubator/ivy/core/trunk/doc/configuration/cache.html Sun Dec 2 07:56:22
2007
@@ -0,0 +1,89 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd";>
+<!--
+ 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.
+-->
+<html>
+<head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<b>Tag:</b> cache
+
+<span class="since">since 2.0</span> Configures the Ivy cache.
+
+Ivy cache is composed of two different parts:
+<ul>
+<li>the repository cache</li>
+The repository cache is where Ivy stores data downloaded from module
repositories, along with some meta information concerning these artifacts, like
their original location.
+This part of the cache can be shared if you use an ad hoc
[[configuration/lock-strategies lock strategy]].
+<li>the resolution cache</li>
+This part of the cache is used to store resolution data, which is used by Ivy
to reuse the results of a resolve process.
+This part of the cache is overwritten each time a new resolve is performed,
and should never be used by multiple processes at the same time.
+</ul>
+
+Here are some details on the available settings attributes:
+
+<em>basedir</em> is the base directory where the cache will be stored. All
other cache related paths are relative to this basedir.
+It usually points to a directory in the local filesystem.
+<strong>This should not point to a directory used as a repository!</strong>
+
+Once the settings are loaded, the value of the defaultCache (either configured
or the default value) is stored in an Ivy variable: ivy.cache.dir.
+
+<em>repositoryDir</em> and <em>resolutionDir</em> are used to configure the
base location of the repository and resolution parts of the cache.
+
+<em>repositoryIvyPattern</em> and <em>repositoryArtifactPattern</em> are used
to configure the way Ivy stores ivy files and artifacts in the cache. Usually
you do not have to change this, unless you want to use the cache directly from
another tool, which is not recommended. These patterns are relative to the
repository cache root.
+
+<em>lockStrategy</em> is used to define the lock strategy to use when
accessing the repository cache.
+
+<h1>Attributes</h1>
+<table class="ivy-attributes">
+<thead>
+ <tr><th class="ivy-att">Attribute</th><th
class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
+</thead>
+<tbody>
+ <tr><td>basedir</td><td>a path to a directory to use as base directory for
the cache.</td>
+ <td>No, defaults to .ivy2/cache in user home</td></tr>
+ <tr><td>resolutionDir</td><td>the path of the directory to use to put all
resolution cache data</td>
+ <td>No, defaults to empty string (ie cache basedir)</td></tr>
+ <tr><td>repositoryDir</td><td>the path of the directory to use to put all
repository cache data</td>
+ <td>No, defaults to empty string (ie cache basedir)</td></tr>
+ <tr><td>repositoryIvyPattern</td><td>a pattern to indicate where ivy files
should be put in the repository cache</td>
+ <td>No, defaults to
[organisation]/[module]/ivy-[revision].xml</td></tr>
+ <tr><td>repositoryArtifactPattern</td><td>a pattern to indicate where
artifact files should be put in repository cache</td>
+ <td>No, defaults to
[organisation]/[module]/[type]s/[artifact]-[revision].[ext]</td></tr>
+ <tr><td>lockStragegy</td><td>the name of the
[[configuration/lock-strategies]] lock strategy to use when accessing the
cache</td>
+ <td>No, defaults to <em>no-lock</em></td></tr>
+</tbody>
+</table>
+<h1>Example</h1>
+<code type="xml">
+<cache basedir="mycache"
+ resolutionDir="resolution"
+ repositoryDir="repository"
+ repositoryIvyPattern="[module]/ivys/ivy-[revision].xml"
+
repositoryArtifactPattern="[module]/[type]s/[artifact]-[revision].[ext]"
+ lockStrategy="artifact-lock"
+/>
+</code>
+</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Propchange: incubator/ivy/core/trunk/doc/configuration/cache.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/ivy/core/trunk/doc/configuration/conf.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/configuration/conf.html?rev=600318&r1=600317&r2=600318&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/configuration/conf.html (original)
+++ incubator/ivy/core/trunk/doc/configuration/conf.html Sun Dec 2 07:56:22
2007
@@ -31,6 +31,8 @@
Default cache is used whenever a cache is not provided. It usually points to a
directory in your filesystem. <strong>This should not point to a directory used
as a repository!</strong>
<span class="since">Since 2.0</span> Once the settings are loaded, the value
of the defaultCache (either configured or the default value) is stored in an
Ivy variable: ivy.cache.dir.
+<span class="since">Since 2.0</span> A new [[configuration/cache]] tag is
provided where you can fully configure the cache. As of 2.0 beta 1, we
recommend using the cache tag even though configuring using the attributes
available on this tag is still possible.
+
Default resolver is used whenever nothing else is configured in the modules
section of the configuration file. It should give the name of a dependency
resolver defined in the resolvers section of the configuration file.
@@ -44,14 +46,13 @@
checkUpToDate indicates to ivy if it must check date of artifacts before
retrieving them (i.e. copying them from
cache to another place in your filesystem). Usually it is a good thing to
check date to avoid unnecessary copy, even if it's most of the time a local
copy.
-cacheIvyPattern and cacheArtifactPattern are used to configure the way ivy
stores ivy files and artifacts in the cache. Usually you do not have to change
this, unless you want to use the cache directly from another tool, which is not
recommended.
<h1>Attributes</h1>
<table class="ivy-attributes">
<thead>
<tr><th class="ivy-att">Attribute</th><th
class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
</thead>
<tbody>
- <tr><td>defaultCache</td><td>a path to a directory to use as default
cache</td>
+ <tr><td>defaultCache</td><td>a path to a directory to use as default
cache. <i>We recommend using the basedir on the [[configuration/cache]] tag
instead</i></td>
<td>No, defaults to .ivy2/cache in user home</td></tr>
<tr><td>defaultResolver</td><td>the name of the default resolver to
use</td>
<td>No, but all modules should be configured in the modules section if
not provided</td></tr>
@@ -67,9 +68,9 @@
<td>No, defaults to true</td></tr>
<tr><td>checkUpToDate</td><td>Indicates if date should be checked before
retrieving artifacts from cache</td>
<td>No, defaults to true</td></tr>
- <tr><td>cacheIvyPattern</td><td>a pattern to indicate where ivy files
should be put in cache</td>
+ <tr><td>cacheIvyPattern</td><td>a pattern to indicate where ivy files
should be put in cache. <i>We recommend using the repositoryIvyPattern on the
[[configuration/cache]] tag instead</i></td>
<td>No, defaults to
[organisation]/[module]/ivy-[revision].xml</td></tr>
- <tr><td>cacheArtifactPattern</td><td>a pattern to indicate where artifact
files should be put in cache</td>
+ <tr><td>cacheArtifactPattern</td><td>a pattern to indicate where artifact
files should be put in cache. <i>We recommend using the
repositoryArtifactPattern on the [[configuration/cache]] tag instead</i></td>
<td>No, defaults to
[organisation]/[module]/[type]s/[artifact]-[revision].[ext]</td></tr>
<tr><td>useRemoteConfig</td><td>true to configure ivyrep and ibiblio
resolver from a remote configuration file (updated with changes in those
repository structure if any) (<span class="since">since 1.2</span>)</td>
<td>No, defaults to false</td></tr>
Added: incubator/ivy/core/trunk/doc/configuration/lock-strategies.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/configuration/lock-strategies.html?rev=600318&view=auto
==============================================================================
--- incubator/ivy/core/trunk/doc/configuration/lock-strategies.html (added)
+++ incubator/ivy/core/trunk/doc/configuration/lock-strategies.html Sun Dec 2
07:56:22 2007
@@ -0,0 +1,62 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd";>
+<!--
+ 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.
+-->
+<html>
+<head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <script type="text/javascript">var xookiConfig = {level: 1};</script>
+ <script type="text/javascript" src="../xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+<b>Tag:</b> lock-strategies <span class="since">since 2.0</span>
+
+Defines a list of lock strategies usable in Ivy.
+
+A lock strategy is used by a cache manager to decide when and how locking
should be performed (see [[configuration/cache]] to see how to configure the
lock strategy to use).
+
+Two lock strategies are registered by default:
+<ul>
+<li><b>no-lock</b></li> This lock strategy actually performs no locking at
all, and thus should not be used in environment where the cache is shared by
multiple processes.
+
+This strategy is implemented by
([[svn:src/java/org/apache/ivy/plugins/lock/NoLockStrategy.java
NoLockStrategy]])
+
+
+<li><b>artifact-lock</b></li> This strategy acquire a lock whenever a module
descriptor or an artifact is downloaded to the cache, which makes a good
solution when you want to share your repository cache.
+
+Note that this strategy is based on file locking, performed by default using
the java.io.File.createNewFile() atomicity (which is documented as atomic in
the javadoc, but not recommended to perform locks). A java.nio.FileLock based
implementation is also provided, but according to our tests the createNewFile
based one performs better and more reliably. We heavily recommend making your
own testing in your target environment before relying on this lock strategy for
heavily concurrent operations.
+
+This strategy is implemented by
([[svn:src/java/org/apache/ivy/plugins/lock/ArtifactLockStrategy.java
ArtifactLockStrategy]])
+</ul>
+
+The child tag used for the lock strategy must be equal to a name of a lock
strategy type (added with the typedef tag).
+
+<h1>Child elements</h1>
+<table class="ivy-children">
+<thead>
+ <tr><th class="ivy-chld">Element</th><th
class="ivy-chld-desc">Description</th><th
class="ivy-chld-card">Cardinality</th></tr>
+</thead>
+<tbody>
+ <tr><td>any lock strategy</td><td>adds a lock strategy to the list of
available ones</td>
+ <td>0..n</td></tr>
+</tbody>
+</table></textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>
Propchange: incubator/ivy/core/trunk/doc/configuration/lock-strategies.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/ivy/core/trunk/doc/extend.html
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/extend.html?rev=600318&r1=600317&r2=600318&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/extend.html (original)
+++ incubator/ivy/core/trunk/doc/extend.html Sun Dec 2 07:56:22 2007
@@ -25,41 +25,30 @@
</head>
<body>
<textarea id="xooki-source">
-Many things are configurable in ivy, and many things are available with ivy
core. But when you want to do
-something not built in ivy core, you can still plug your own code.<br/><br/>
+Many things are configurable in Ivy, and many things are available with Ivy
core. But when you want to do something not built in ivy core, you can still
plug your own code.
-Several things are pluggable in ivy:
+Many things are pluggable in Ivy:
<ul>
<li>module descriptor parsers</li>
<li>dependency resolvers</li>
+<li>lock strategies</li>
<li>latest strategies</li>
+<li>circular dependency strategies</li>
<li>conflict managers</li>
<li>report outputters</li>
<li>version matchers</li>
<li>triggers</li>
</ul>
-Before trying to implement your own, we encourage you to check if the solution
to your problem cannot be
-addressed by existing features, or by [[links contributed ones]]. Do not
hesitate to ask for help on the [[mailing-lists]].<br/><br/>
+Before trying to implement your own, we encourage you to check if the solution
to your problem cannot be addressed by existing features, or by [[links
contributed ones]]. Do not hesitate to ask for help on the [[mailing-lists]].
-If you still don't find what you need, then you'll have to develop your own
plugin or find someone who could do that for you.<br/><br/>
+If you still don't find what you need, then you'll have to develop your own
plugin or find someone who could do that for you.
-Here are the main things to know if you want to develop your own
plugins...<br/><br/>
+All ivy plug-ins use the same code patterns as ant specific tasks for
parameters. This means that if you want to have a "myattribute" of type String,
you just have to declare a method called setMyattribute(String val) on your
plug-in. The same applies to child tags, you just have to follow Ant
specifications.
-All ivy plug-ins use the same code patterns as ant specific tasks for
parameters. This means that
-if you want to have a "myattribute" of type String, you just have to declare a
method called
-setMyattribute(String val) on your plug-in. The same applies to child tags,
you just have to follow ant specifications.<br/><br/>
-
-Knowing that, you then have to implement the appropriate interface:
-<ul>
-<li>org.apache.ivy.DependencyResolver for dependency resolvers</li>
-<li>org.apache.ivy.LatestStrategy for latest strategies</li>
-<li>org.apache.ivy.ConflictManager for conflict managers</li>
-<li>org.apache.ivy.parser.ModuleDescriptorParser for module descriptor
parsers</li>
-</ul>
-
-To help you understand what is required in each implementation, and what you
can use to do it, have a look to existing implementations, it's the best advice
we can give you!
+All pluggable code in Ivy is located in the
[[svn:src/java/org/apache/ivy/plugins org.apache.ivy.plugins]] package. In each
package you will find an interface that you must implement to provide a new
plugin. We usually also provide an abstract class easing the implementation and
making your code more independent of interface changes. We heavily recommend
using these abstract classes as a base class.
+To understand how your implementation can be done, we suggest looking at
existing implementations we provide, it's the best way to get started.
</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
Modified: incubator/ivy/core/trunk/doc/toc.json
URL:
http://svn.apache.org/viewvc/incubator/ivy/core/trunk/doc/toc.json?rev=600318&r1=600317&r2=600318&view=diff
==============================================================================
--- incubator/ivy/core/trunk/doc/toc.json (original)
+++ incubator/ivy/core/trunk/doc/toc.json Sun Dec 2 07:56:22 2007
@@ -193,6 +193,20 @@
]
},
{
+ "id":"configuration/lock-strategies",
+ "title":"lock-strategies",
+ "children": [
+
+ ]
+ },
+ {
+ "id":"configuration/cache",
+ "title":"cache",
+ "children": [
+
+ ]
+ },
+ {
"id":"configuration/latest-strategies",
"title":"latest-strategies",
"children": [
