incubator-ivy-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From xav...@apache.org
Subject svn commit: r600318 - in /incubator/ivy/core/trunk/doc: configuration.html configuration/cache.html configuration/conf.html configuration/lock-strategies.html extend.html toc.json
Date Sun, 02 Dec 2007 15:56:23 GMT
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": [



Mime
View raw message