From baf03a919c75822d1dcdaa7ffd460ec635b6a50f Mon Sep 17 00:00:00 2001 From: twogee Date: Sun, 28 May 2017 11:30:37 +0200 Subject: [PATCH] Make Java 8 doclint happy; adjust javadoc Ant target; remove connection to svn from build.xml --- build.xml | 405 +++++++++--------- src/java/org/apache/ivy/Ivy.java | 50 ++- src/java/org/apache/ivy/Ivy14.java | 8 +- .../org/apache/ivy/ant/AntBuildTrigger.java | 10 +- .../org/apache/ivy/ant/IvyAntSettings.java | 7 +- src/java/org/apache/ivy/ant/IvyBuildList.java | 10 +- src/java/org/apache/ivy/ant/IvyPublish.java | 2 + src/java/org/apache/ivy/ant/IvyResolve.java | 1 + src/java/org/apache/ivy/ant/IvyRetrieve.java | 12 +- src/java/org/apache/ivy/ant/IvyTask.java | 4 +- src/java/org/apache/ivy/core/IvyContext.java | 26 +- .../apache/ivy/core/RelativeUrlResolver.java | 9 +- .../apache/ivy/core/cache/ArtifactOrigin.java | 15 +- .../cache/DefaultRepositoryCacheManager.java | 38 +- .../apache/ivy/core/check/CheckEngine.java | 4 + .../ivy/core/deliver/DeliverEngine.java | 8 +- .../ivy/core/deliver/DeliverOptions.java | 31 +- .../org/apache/ivy/core/event/IvyEvent.java | 24 +- .../apache/ivy/core/event/IvyEventFilter.java | 9 +- .../DefaultDependencyDescriptor.java | 36 +- .../descriptor/DefaultModuleDescriptor.java | 21 +- .../DependencyArtifactDescriptor.java | 22 +- .../descriptor/DependencyDescriptor.java | 24 +- .../module/descriptor/ExtendsDescriptor.java | 32 +- .../module/descriptor/ModuleDescriptor.java | 133 ++---- .../apache/ivy/core/module/id/ArtifactId.java | 4 +- .../ivy/core/module/id/MatcherLookup.java | 22 +- .../ivy/core/publish/PublishEngine.java | 7 + .../report/ConfigurationResolveReport.java | 25 +- .../ivy/core/report/DownloadStatus.java | 3 +- .../apache/ivy/core/report/ResolveReport.java | 22 +- .../org/apache/ivy/core/resolve/IvyNode.java | 57 ++- .../ivy/core/resolve/IvyNodeCallers.java | 3 +- .../ivy/core/resolve/IvyNodeEviction.java | 10 +- .../ivy/core/resolve/ResolveEngine.java | 47 +- .../ivy/core/resolve/ResolveOptions.java | 13 +- .../apache/ivy/core/resolve/VisitNode.java | 22 +- .../ivy/core/retrieve/RetrieveEngine.java | 9 +- .../ivy/core/retrieve/RetrieveReport.java | 10 + .../apache/ivy/core/search/SearchEngine.java | 20 +- .../apache/ivy/core/settings/IvySettings.java | 33 +- .../core/sort/CollectionOfModulesToSort.java | 6 +- .../ivy/core/sort/ModuleDescriptorSorter.java | 14 +- .../apache/ivy/core/sort/ModuleInSort.java | 17 +- .../ivy/osgi/core/BundleInfoAdapter.java | 7 +- .../ivy/osgi/util/DelegatingHandler.java | 108 +++-- .../circular/CircularDependencyHelper.java | 5 +- .../LatestCompatibleConflictManager.java | 16 +- .../latest/WorkspaceLatestStrategy.java | 4 +- .../plugins/lock/FileBasedLockStrategy.java | 19 +- .../apache/ivy/plugins/lock/LockStrategy.java | 11 +- .../matcher/ExactOrRegexpPatternMatcher.java | 5 +- .../plugins/matcher/ExactPatternMatcher.java | 3 +- .../plugins/matcher/GlobPatternMatcher.java | 10 +- .../ivy/plugins/matcher/PatternMatcher.java | 7 +- .../parser/ModuleDescriptorParser.java | 8 +- .../ivy/plugins/parser/ParserSettings.java | 2 +- .../parser/m2/PomModuleDescriptorParser.java | 12 +- .../ivy/plugins/parser/m2/PomReader.java | 3 + .../parser/xml/XmlModuleDescriptorParser.java | 60 ++- .../xml/XmlModuleDescriptorUpdater.java | 17 +- .../ivy/plugins/report/XmlReportParser.java | 2 + .../ivy/plugins/repository/Repository.java | 45 +- .../ivy/plugins/repository/Resource.java | 12 +- .../ivy/plugins/repository/TransferEvent.java | 36 +- .../ssh/AbstractSshBasedRepository.java | 13 +- .../ivy/plugins/repository/ssh/SshCache.java | 22 +- .../plugins/repository/ssh/SshRepository.java | 25 +- .../plugins/repository/vfs/VfsRepository.java | 14 +- .../plugins/repository/vfs/VfsResource.java | 16 +- .../repository/vsftp/VsftpRepository.java | 9 +- .../resolver/AbstractSshBasedResolver.java | 16 +- .../plugins/resolver/DependencyResolver.java | 46 +- .../ivy/plugins/resolver/SshResolver.java | 16 +- .../resolver/WorkspaceChainResolver.java | 6 +- .../resolver/packager/PackagerCacheEntry.java | 12 +- .../resolver/packager/PackagerResolver.java | 27 +- .../ivy/plugins/version/VersionMatcher.java | 14 +- src/java/org/apache/ivy/util/FileUtil.java | 57 ++- src/java/org/apache/ivy/util/StringUtils.java | 11 +- src/java/org/apache/ivy/util/XMLHelper.java | 21 +- .../apache/ivy/util/filter/FilterHelper.java | 16 +- .../org/apache/ivy/util/url/URLHandler.java | 51 +-- .../ivy/util/url/URLHandlerRegistry.java | 2 +- 84 files changed, 1151 insertions(+), 920 deletions(-) diff --git a/build.xml b/build.xml index d6f50b50..e16296c6 100644 --- a/build.xml +++ b/build.xml @@ -18,50 +18,50 @@ --> - - - + + + - + - + - + - + - + - + - - + + - + - - - + + - - + - - + + + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf-local.xml"/> + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf-default-chain.xml"/> + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf-main-chain.xml"/> + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf-public.xml"/> + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf-shared.xml"/> + tofile="${core.classes.build.dir}/org/apache/ivy/core/settings/ivyconf.xml"/> @@ -228,18 +228,18 @@ target="${ivy.minimum.javaversion}" debug="${debug.mode}" includeantruntime="yes"> - + - - + + - + - + - - + + + todir="${ant.classes.build.dir}/fr/jayasoft/ivy/ant"/> - + - - + + - - + + @@ -285,10 +285,10 @@ - + - - + + @@ -299,38 +299,38 @@ --> - + - - - + + + - + - - - - - - - - - + + + + + + + + + - + + tofile="${artifacts.build.dir}/org.apache.ivy_${bundle.version}.jar"/> - + - + + includeantruntime="no"/> + basedir="${build.dir}/custom-classpath"/> - - - + + + - - + + - + + log="download-only"/> + log="download-only"/> - - + + - - - - - + + + + + - - - + + + - + - - + + @@ -419,30 +419,30 @@ target="${ivy.minimum.javaversion}" debug="${debug.mode}" encoding="ISO-8859-1" - includeantruntime="no" /> + includeantruntime="no"/> - + - + - + - + - + - - + + - + - - - - + + + + - - + + - + @@ -481,7 +481,7 @@ - + @@ -490,7 +490,7 @@ + message="At least one test has failed. See logs (in ${test.xml.dir}) for details (use the target test-report to run the test with a report)"/> @@ -572,35 +578,35 @@ - + - + - + - + - + - + + message="Checkstyle has errors. See report in ${checkstyle.report.dir}"/> - + - + @@ -625,8 +631,7 @@ property="findbugs.home" value="${findbugs.download.to}/${findbugs.download.name}" file="${findbugs.download.to}/${findbugs.download.name}/lib/findbugs.jar" - description="Check if Findbugs is already installed." - /> + description="Check if Findbugs is already installed."/> - + @@ -665,8 +670,8 @@ outputFile="${findbugs.reportdir}/${findbugs.raw}" jvmargs="${findbugs.jvmargs}" projectName="${Name} ${project.version}"> - - + + @@ -680,24 +685,24 @@ - + + validargs="Y,N,y,n" addproperty="eclipse.classpath.confirm"/> - + - - + - + diff --git a/src/java/org/apache/ivy/Ivy.java b/src/java/org/apache/ivy/Ivy.java index 1a57ce99..88767393 100644 --- a/src/java/org/apache/ivy/Ivy.java +++ b/src/java/org/apache/ivy/Ivy.java @@ -76,6 +76,7 @@ import org.apache.ivy.util.MessageLoggerEngine; * Ivy is a free java based dependency manager. *

* This class is the main class of Ivy, which acts as a Facade to all services offered by Ivy: + *

* * Here is one typical usage: - * * 
  * Ivy ivy = Ivy.newInstance();
  * ivy.configure(new URL("ivysettings.xml"));
  * ivy.resolve(new URL("ivy.xml"));
  *
- * - *

*

Using Ivy engines directly

*

* If the methods offered by the {@link Ivy} class are not flexible enough and you want to use Ivy * engines directly, you need to call the methods within a single {@link IvyContext} associated to - * the {@link Ivy} instance you use.
+ * the {@link Ivy} instance you use. + *

+ *

* To do so, it is recommended to use the {@link #execute(org.apache.ivy.Ivy.IvyCallback)} method * like this: - * + *

* 
  * Ivy ivy = Ivy.newInstance();
  * ivy.execute(new IvyCallback() {
@@ -111,19 +111,17 @@ import org.apache.ivy.util.MessageLoggerEngine;
  *     }
  * });
  *
- * - *

*/ public class Ivy { /** * Callback used to execute a set of Ivy related methods within an {@link IvyContext}. - * + * * @see Ivy#execute(org.apache.ivy.Ivy.IvyCallback) */ public static interface IvyCallback { /** * Executes Ivy related job within an {@link IvyContext} - * + * * @param ivy * the {@link Ivy} instance to which this callback is related * @param context @@ -171,7 +169,7 @@ public class Ivy { /** * Returns the current version of Ivy, as displayed on the console when Ivy is initialized. - * + * * @return the current version of Ivy */ public static String getIvyVersion() { @@ -180,9 +178,8 @@ public class Ivy { /** * Returns the date at which this version of Ivy has been built. - *

- * May be empty if unknown. - * + *

May be empty if unknown.

+ * * @return the date at which this version of Ivy has been built */ public static String getIvyDate() { @@ -191,7 +188,7 @@ public class Ivy { /** * Returns the URL at which Ivy web site can be found. - * + * * @return the URL at which Ivy web site can be found */ public static String getIvyHomeURL() { @@ -218,7 +215,7 @@ public class Ivy { /** * True if this instance of Ivy has already been bound to its dependencies, false otherwise. - * + * * @see #bind() */ private boolean bound; @@ -344,7 +341,7 @@ public class Ivy { *

* Alternatively you can use the {@link #pushContext()} and {@link #popContext()} methods, but * this is not recommended: - * + *

* 
      * Object result = null;
      * pushContext();
@@ -355,9 +352,7 @@ public class Ivy {
      * }
      * doSomethingWithResult(result);
      *
- * - *

- * + * * @param callback IvyCallback * @return Object */ @@ -446,6 +441,9 @@ public class Ivy { /** * Configures Ivy with 1.4 compatible default settings + * + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public void configureDefault14() throws ParseException, IOException { pushContext(); @@ -594,13 +592,13 @@ public class Ivy { /** * Example of use: deliver(mrid, "1.5", "target/ivy/ivy-[revision].xml", * DeliverOptions.newInstance(settings).setStatus("release").setValidate(false)); - * + * * @param mrid ModuleRevisionId * @param revision String * @param destIvyPattern String * @param options DeliverOptions - * @throws IOException - * @throws ParseException + * @throws IOException if something goes wrong + * @throws ParseException if something goes wrong */ public void deliver(ModuleRevisionId mrid, String revision, String destIvyPattern, DeliverOptions options) throws IOException, ParseException { @@ -633,6 +631,10 @@ public class Ivy { /** * Sorts the collection of IvyNode from the less dependent to the more dependent + * + * @param nodes Collection<IvyNode> + * @param options SortOptions + * @return List<IvyNode> */ public List sortNodes(Collection nodes, SortOptions options) { pushContext(); @@ -647,7 +649,7 @@ public class Ivy { * Sorts the given ModuleDescriptors from the less dependent to the more dependent. This sort * ensures that a ModuleDescriptor is always found in the list before all ModuleDescriptors * depending directly on it. - * + * * @param moduleDescriptors * a Collection of ModuleDescriptor to sort * @param options @@ -779,6 +781,8 @@ public class Ivy { /** * Interrupts the current running operation in the given operating thread, no later than * interruptTimeout milliseconds after the call + * + * @param operatingThread Thread */ @SuppressWarnings("deprecation") public void interrupt(Thread operatingThread) { diff --git a/src/java/org/apache/ivy/Ivy14.java b/src/java/org/apache/ivy/Ivy14.java index 0ae8b7a6..28bc4ca0 100644 --- a/src/java/org/apache/ivy/Ivy14.java +++ b/src/java/org/apache/ivy/Ivy14.java @@ -61,17 +61,17 @@ import org.apache.ivy.util.filter.FilterHelper; * instance of this class. *

* For instance, where you were doing: - * + * * 

  * Ivy ivy = new Ivy();
  *
- * + * * do instead: - * + * * 
  * Ivy14 ivy = new Ivy14();
  *
- * + * * And that should be enough in most cases! */ public class Ivy14 { diff --git a/src/java/org/apache/ivy/ant/AntBuildTrigger.java b/src/java/org/apache/ivy/ant/AntBuildTrigger.java index 96f38136..19503333 100644 --- a/src/java/org/apache/ivy/ant/AntBuildTrigger.java +++ b/src/java/org/apache/ivy/ant/AntBuildTrigger.java @@ -38,14 +38,14 @@ import org.apache.tools.ant.taskdefs.Property; * Triggers an ant build on an event occurrence. *

* Example of use: - * + *

* 
- * <ant-build-trigger event="pre-resolve-dependency" 
+ * <ant-build-trigger event="pre-resolve-dependency"
  *                    filter="revision=latest.integration"
- *                    antfile="/path/to/[module]/build.xml" 
+ *                    antfile="/path/to/[module]/build.xml"
  *                    target="compile"/>
  *
- * + *

* Triggers an ant build for any dependency in asked in latest.integration, just before resolving * the dependency. *

@@ -53,7 +53,7 @@ import org.apache.tools.ant.taskdefs.Property; * The onlyonce property is used to tell if the ant build should be triggered only once, or several * times in the same build. *

- * + * * @see AntCallTrigger * @since 1.4 */ diff --git a/src/java/org/apache/ivy/ant/IvyAntSettings.java b/src/java/org/apache/ivy/ant/IvyAntSettings.java index 64efc9e9..9f169d60 100644 --- a/src/java/org/apache/ivy/ant/IvyAntSettings.java +++ b/src/java/org/apache/ivy/ant/IvyAntSettings.java @@ -107,7 +107,7 @@ public class IvyAntSettings extends DataType { /** * Returns the default ivy settings of this classloader. If it doesn't exist yet, a new one is * created using the given project to back the VariableContainer. - * + * * @param task * TODO add text. * @return An IvySetting instance. @@ -241,7 +241,8 @@ public class IvyAntSettings extends DataType { /** * Return the configured Ivy instance. - * + * + * @param task ProjectComponent * @return Returns the configured Ivy instance. */ public Ivy getConfiguredIvyInstance(ProjectComponent task) { @@ -336,7 +337,7 @@ public class IvyAntSettings extends DataType { /** * Set file or url to its default value - * + * * @param variableContainer IvyVariableContainer */ private void defineDefaultSettingFile(IvyVariableContainer variableContainer, diff --git a/src/java/org/apache/ivy/ant/IvyBuildList.java b/src/java/org/apache/ivy/ant/IvyBuildList.java index 55cbe748..bdc9ab92 100644 --- a/src/java/org/apache/ivy/ant/IvyBuildList.java +++ b/src/java/org/apache/ivy/ant/IvyBuildList.java @@ -352,7 +352,7 @@ public class IvyBuildList extends IvyTask { /** * Returns a collection of ModuleDescriptors that are contained in the input collection of * ModuleDescriptors and upon which the root module depends - * + * * @param mds * input collection of ModuleDescriptors * @param rootmds @@ -393,7 +393,7 @@ public class IvyBuildList extends IvyTask { * Adds the current node to the toKeep collection and then processes the each of the direct * dependencies of this node that appear in the moduleIdMap (indicating that the dependency is * part of this BuildList) - * + * * @param node * the node to be processed * @param toKeep @@ -423,7 +423,7 @@ public class IvyBuildList extends IvyTask { /** * Returns a collection of ModuleDescriptors that are contained in the input collection of * ModuleDescriptors which depends on the leaf module - * + * * @param mds * input collection of ModuleDescriptors * @param leafmds @@ -461,7 +461,7 @@ public class IvyBuildList extends IvyTask { /** * Search in the moduleIdMap modules depending on node, add them to the toKeep set and process * them recursively. - * + * * @param node * the node to be processed * @param toKeep @@ -520,6 +520,7 @@ public class IvyBuildList extends IvyTask { } /** + * @return boolean * @deprecated use {@link #getOnMissingDescriptor()} instead. */ @Deprecated @@ -528,6 +529,7 @@ public class IvyBuildList extends IvyTask { } /** + * @param skipBuildFilesWithoutIvy boolean * @deprecated use {@link #setOnMissingDescriptor(String)} instead. */ @Deprecated diff --git a/src/java/org/apache/ivy/ant/IvyPublish.java b/src/java/org/apache/ivy/ant/IvyPublish.java index 1c2921b2..97952314 100644 --- a/src/java/org/apache/ivy/ant/IvyPublish.java +++ b/src/java/org/apache/ivy/ant/IvyPublish.java @@ -98,6 +98,7 @@ public class IvyPublish extends IvyTask { } /** + * @return String * @deprecated use {@link #getSrcivypattern()} instead. */ @Deprecated @@ -106,6 +107,7 @@ public class IvyPublish extends IvyTask { } /** + * @param destivypattern String * @deprecated use {@link #setSrcivypattern(String)} instead. */ @Deprecated diff --git a/src/java/org/apache/ivy/ant/IvyResolve.java b/src/java/org/apache/ivy/ant/IvyResolve.java index 5a30ab5f..8e42f71a 100644 --- a/src/java/org/apache/ivy/ant/IvyResolve.java +++ b/src/java/org/apache/ivy/ant/IvyResolve.java @@ -193,6 +193,7 @@ public class IvyResolve extends IvyTask { } /** + * @param failureProperty String * @deprecated Use {@link #setFailureProperty(String)} instead */ @Deprecated diff --git a/src/java/org/apache/ivy/ant/IvyRetrieve.java b/src/java/org/apache/ivy/ant/IvyRetrieve.java index 20695d93..c7838277 100644 --- a/src/java/org/apache/ivy/ant/IvyRetrieve.java +++ b/src/java/org/apache/ivy/ant/IvyRetrieve.java @@ -159,6 +159,8 @@ public class IvyRetrieve extends IvyPostResolveTask { /** * Option to create symlinks instead of copying. + * + * @param symlink boolean */ public void setSymlink(boolean symlink) { this.symlink = symlink; @@ -166,6 +168,8 @@ public class IvyRetrieve extends IvyPostResolveTask { /** * Option to create symlinks in one mass action, instead of separately. + * + * @param symlinkmass boolean */ public void setSymlinkmass(boolean symlinkmass) { this.symlinkmass = symlinkmass; @@ -185,9 +189,9 @@ public class IvyRetrieve extends IvyPostResolveTask { /** * Add a mapper to convert the file names. - * + * * @param mapper - * a Mapper value. + * a Mapper value. */ public void addMapper(Mapper mapper) { if (this.mapper != null) { @@ -198,7 +202,7 @@ public class IvyRetrieve extends IvyPostResolveTask { /** * Add a nested filenamemapper. - * + * * @param fileNameMapper * the mapper to add. */ @@ -210,7 +214,7 @@ public class IvyRetrieve extends IvyPostResolveTask { /** * Returns the path of the file relative to the given base directory. - * + * * @param base * the parent directory to which the file must be evaluated. * @param file diff --git a/src/java/org/apache/ivy/ant/IvyTask.java b/src/java/org/apache/ivy/ant/IvyTask.java index 42997d98..a421447f 100644 --- a/src/java/org/apache/ivy/ant/IvyTask.java +++ b/src/java/org/apache/ivy/ant/IvyTask.java @@ -278,8 +278,8 @@ public abstract class IvyTask extends Task { /** * The real logic of task execution after project has been set in the context. MUST be * implemented by subclasses - * - * @throws BuildException + * + * @throws BuildException if something goes wrong */ public abstract void doExecute() throws BuildException; diff --git a/src/java/org/apache/ivy/core/IvyContext.java b/src/java/org/apache/ivy/core/IvyContext.java index 4ff0f3b9..ab735114 100644 --- a/src/java/org/apache/ivy/core/IvyContext.java +++ b/src/java/org/apache/ivy/core/IvyContext.java @@ -36,7 +36,7 @@ import org.apache.ivy.util.MessageLogger; /** * This class represents an execution context of an Ivy action. It contains several getters to * retrieve information, like the used Ivy instance, the cache location... - * + * * @see IvyThread */ public class IvyContext { @@ -90,7 +90,7 @@ public class IvyContext { * {@link #popContext()} should usually be called when the job for which this context has been * pushed is finished. *

- * + * * @return the newly pushed context */ public static IvyContext pushNewContext() { @@ -104,7 +104,7 @@ public class IvyContext { * {@link #popContext()} should usually be called when the job for which this context has been * pushed is finished. *

- * + * * @return the newly pushed context */ public static IvyContext pushNewCopyContext() { @@ -115,7 +115,7 @@ public class IvyContext { * Changes the context associated with this thread. This is especially useful when launching a * new thread, to associate it with the same context as the initial one. Do not forget to call * {@link #popContext()} when done. - * + * * @param context * the new context to use in this thread. * @return the pushed context @@ -129,7 +129,7 @@ public class IvyContext { * Pops one context used with this thread. This is usually called after having finished a task * for which a call to {@link #pushNewContext()} or {@link #pushContext(IvyContext)} was done * prior to beginning the task. - * + * * @return the popped context */ public static IvyContext popContext() { @@ -144,7 +144,7 @@ public class IvyContext { * This methods does a similar job to {@link #peek(String)}, except that it considers the whole * context stack and not only one instance. *

- * + * * @param key * context key for the string * @return top object from the list (index 0) of the first context in the stack containing this @@ -172,7 +172,7 @@ public class IvyContext { * Then, or if no ivy method has been called, a default ivy instance is returned by this method, * so that it never returns null. *

- * + * * @return the current ivy instance */ public Ivy getIvy() { @@ -187,7 +187,7 @@ public class IvyContext { * If you want get a default Ivy instance in case no instance if currently associated, use * {@link #getIvy()}. *

- * + * * @return the current ivy instance, or null if there is no current ivy instance. */ public Ivy peekIvy() { @@ -233,7 +233,7 @@ public class IvyContext { /** * Reads the first object from the list saved under given key in the context. If value under key * represents non List object then a RuntimeException is thrown. - * + * * @param key * context key for the string * @return top object from the list (index 0) or null if no key or list empty @@ -259,7 +259,7 @@ public class IvyContext { /** * Removes and returns first object from the list saved under given key in the context. If value * under key represents non List object then a RuntimeException is thrown. - * + * * @param key * context key for the string * @return top object from the list (index 0) or null if no key or list empty @@ -286,9 +286,11 @@ public class IvyContext { * Removes and returns first object from the list saved under given key in the context but only * if it equals the given expectedValue - if not a false value is returned. If value under key * represents non List object then a RuntimeException is thrown. - * + * * @param key * context key for the string + * @param expectedValue + * expected value of the key * @return true if the r */ public boolean pop(String key, Object expectedValue) { @@ -318,7 +320,7 @@ public class IvyContext { * under key represents non List object then a RuntimeException is thrown. If no list exists * under given key a new LinkedList is created. This is kept without WeakReference in opposite * to the put() results. - * + * * @param key * key context key for the string * @param value diff --git a/src/java/org/apache/ivy/core/RelativeUrlResolver.java b/src/java/org/apache/ivy/core/RelativeUrlResolver.java index abf6f017..701c4c5a 100644 --- a/src/java/org/apache/ivy/core/RelativeUrlResolver.java +++ b/src/java/org/apache/ivy/core/RelativeUrlResolver.java @@ -28,19 +28,20 @@ public abstract class RelativeUrlResolver { /** * Resolve the url in the context of context. - * + * * @param context * The URL of the resource containing the reference url * @param url * a relative or absolution url string - * @throws MalformedURLException + * @return URL + * @throws MalformedURLException if url is wrong */ public abstract URL getURL(URL context, String url) throws MalformedURLException; /** * Resolve file or url path relatively to a context. file is considered first. If file is not * defined, url will be considered. - * + * * @param context * The URL of the resource containing the reference file or url * @param file @@ -48,7 +49,7 @@ public abstract class RelativeUrlResolver { * @param url * a relative or absolution url string * @return the resulting url or null if failed and url are null. - * @throws MalformedURLException + * @throws MalformedURLException if url is wrong */ public URL getURL(URL context, String file, String url) throws MalformedURLException { if (file != null) { diff --git a/src/java/org/apache/ivy/core/cache/ArtifactOrigin.java b/src/java/org/apache/ivy/core/cache/ArtifactOrigin.java index 66dc5f53..7e397af0 100644 --- a/src/java/org/apache/ivy/core/cache/ArtifactOrigin.java +++ b/src/java/org/apache/ivy/core/cache/ArtifactOrigin.java @@ -22,7 +22,7 @@ import org.apache.ivy.util.Checks; /** * This class contains information about the origin of an artifact. - * + * * @see org.apache.ivy.plugins.resolver.BasicResolver * @see org.apache.ivy.plugins.resolver.util.ResolvedResource */ @@ -31,6 +31,9 @@ public class ArtifactOrigin { /** * ArtifactOrigin instance used when the origin is unknown. + * + * @param artifact ditto + * @return ArtifactOrigin */ public static final ArtifactOrigin unknown(Artifact artifact) { return new ArtifactOrigin(artifact, false, UNKNOWN); @@ -58,7 +61,7 @@ public class ArtifactOrigin { /** * Create a new instance - * + * * @param artifact * the artifact pointed by this location. Must not be null. * @param isLocal @@ -77,7 +80,7 @@ public class ArtifactOrigin { /** * Is this resource local to this host, i.e. is it on the file system? - * + * * @return boolean value indicating if the resource is local. */ public boolean isLocal() { @@ -86,7 +89,7 @@ public class ArtifactOrigin { /** * Return the location of the resource (normally a url) - * + * * @return the location of the resource */ public String getLocation() { @@ -99,7 +102,7 @@ public class ArtifactOrigin { /** * Return the artifact that this location is pointing at. - * + * * @return the artifact that this location is pointing at. */ public Artifact getArtifact() { @@ -109,7 +112,7 @@ public class ArtifactOrigin { /** * The last time the resource was checked to be up to date. Maybe null if this * information is not actually used by in some case. - * + * * @return Long timestamp */ public Long getLastChecked() { diff --git a/src/java/org/apache/ivy/core/cache/DefaultRepositoryCacheManager.java b/src/java/org/apache/ivy/core/cache/DefaultRepositoryCacheManager.java index f659d879..ea017971 100644 --- a/src/java/org/apache/ivy/core/cache/DefaultRepositoryCacheManager.java +++ b/src/java/org/apache/ivy/core/cache/DefaultRepositoryCacheManager.java @@ -306,7 +306,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * True if this cache should check lastmodified date to know if ivy files are up to date. - * + * * @return boolean */ public boolean isCheckmodified() { @@ -324,6 +324,8 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * True if this cache should use artifacts original location when possible, false if they should * be copied to cache. + * + * @return boolean */ public boolean isUseOrigin() { if (useOrigin == null) { @@ -340,6 +342,9 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv * Returns a File object pointing to where the artifact can be found on the local file system. * This is usually in the cache, but it can be directly in the repository if it is local and if * the resolve has been done with useOrigin = true + * + * @param artifact Artifact + * @return File */ public File getArchiveFileInCache(Artifact artifact) { ArtifactOrigin origin = getSavedArtifactOrigin(artifact); @@ -350,6 +355,10 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv * Returns a File object pointing to where the artifact can be found on the local file system. * This is usually in the cache, but it can be directly in the repository if it is local and if * the resolve has been done with useOrigin = true + * + * @param artifact Artifact + * @param origin ArtifactOrigin + * @return File */ public File getArchiveFileInCache(Artifact artifact, ArtifactOrigin origin) { File archive = new File(getRepositoryCacheRoot(), getArchivePathInCache(artifact, origin)); @@ -368,6 +377,11 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv * using or not the original location depending on the availability of origin information * provided as parameter and the setting of useOrigin. If useOrigin is false, this method will * always return the file in the cache. + * + * @param artifact Artifact + * @param origin ArtifactOrigin + * @param useOrigin boolean + * @return File */ private File getArchiveFileInCache(Artifact artifact, ArtifactOrigin origin, boolean useOrigin) { if (useOrigin && !ArtifactOrigin.isUnknown(origin) && origin.isLocal()) { @@ -390,7 +404,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Saves the information of which resolver was used to resolve a md, so that this info can be * retrieve later (even after a jvm restart) by getSavedResolverName(ModuleDescriptor md) - * + * * @param md * the module descriptor resolved * @param name @@ -406,7 +420,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Saves the information of which resolver was used to resolve a md, so that this info can be * retrieve later (even after a jvm restart) by getSavedArtResolverName(ModuleDescriptor md) - * + * * @param md * the module descriptor resolved * @param metadataResolverName @@ -573,7 +587,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Creates the unique prefix key that will reference the artifact within the properties. - * + * * @param artifact * the artifact to create the unique key from. Cannot be null. * @return the unique prefix key as a string. @@ -588,7 +602,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Returns the key used to identify the location of the artifact. - * + * * @param artifact * the artifact to generate the key from. Cannot be null. * @return the key to be used to reference the artifact location. @@ -600,7 +614,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Returns the key used to identify if the artifact is local. - * + * * @param artifact * the artifact to generate the key from. Cannot be null. * @return the key to be used to reference the artifact locality. @@ -612,7 +626,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Returns the key used to identify the last time the artifact was checked to be up to date. - * + * * @param artifact * the artifact to generate the key from. Cannot be null. * @return the key to be used to reference the artifact's last check date. @@ -624,7 +638,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Returns the key used to identify the existence of the remote artifact. - * + * * @param artifact * the artifact to generate the key from. Cannot be null. * @return the key to be used to reference the existence of the artifact. @@ -636,7 +650,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Returns the key used to identify the original artifact. - * + * * @param artifact * the artifact to generate the key from. Cannot be null. * @return the key to be used to reference the original artifact. @@ -786,7 +800,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Choose write module descriptor parser for a given moduleDescriptor - * + * * @param moduleDescriptorFile * a given module descriptor * @return ModuleDescriptorParser @@ -1153,7 +1167,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Compute a SHA1 of the resource name, encoded in base64, so we can use it as a file name. - * + * * @param resource * the resource which name will be hashed * @return the hash @@ -1169,7 +1183,7 @@ public class DefaultRepositoryCacheManager implements RepositoryCacheManager, Iv /** * Check that a cached file can be considered up to date and thus not downloaded - * + * * @param archiveFile * the file in the cache * @param resource diff --git a/src/java/org/apache/ivy/core/check/CheckEngine.java b/src/java/org/apache/ivy/core/check/CheckEngine.java index 34d63231..8f85f4ba 100644 --- a/src/java/org/apache/ivy/core/check/CheckEngine.java +++ b/src/java/org/apache/ivy/core/check/CheckEngine.java @@ -52,6 +52,10 @@ public class CheckEngine { * are available in the corresponding resolver. Note that the check is not performed * recursively, i.e. if a dependency has itself dependencies badly described or not available, * this check will not discover it. + * + * @param ivyFile URL + * @param resolvername String + * @return boolean */ public boolean check(URL ivyFile, String resolvername) { try { diff --git a/src/java/org/apache/ivy/core/deliver/DeliverEngine.java b/src/java/org/apache/ivy/core/deliver/DeliverEngine.java index 05ac1c7f..11a843ad 100644 --- a/src/java/org/apache/ivy/core/deliver/DeliverEngine.java +++ b/src/java/org/apache/ivy/core/deliver/DeliverEngine.java @@ -53,13 +53,15 @@ public class DeliverEngine { * Delivers a resolved ivy file based upon last resolve call status. If resolve report file * cannot be found in cache, then it throws an IllegalStateException (maybe resolve has not been * called before ?). - * + * * @param revision * the revision to which the module should be delivered * @param destIvyPattern * the pattern to which the delivered ivy file should be written * @param options * the options with which deliver should be done + * @throws IOException if something goes wrong + * @throws ParseException if something goes wrong */ public void deliver(String revision, String destIvyPattern, DeliverOptions options) throws IOException, ParseException { @@ -86,7 +88,7 @@ public class DeliverEngine { * Delivers a resolved ivy file based upon last resolve call status. If resolve report file * cannot be found in cache, then it throws an IllegalStateException (maybe resolve has not been * called before ?). - * + * * @param mrid * the module revision id of the module to deliver * @param revision @@ -95,6 +97,8 @@ public class DeliverEngine { * the pattern to which the delivered ivy file should be written * @param options * the options with which deliver should be done + * @throws IOException if something goes wrong + * @throws ParseException if something goes wrong */ public void deliver(ModuleRevisionId mrid, String revision, String destIvyPattern, DeliverOptions options) throws IOException, ParseException { diff --git a/src/java/org/apache/ivy/core/deliver/DeliverOptions.java b/src/java/org/apache/ivy/core/deliver/DeliverOptions.java index 6577b7a9..05b70d5e 100644 --- a/src/java/org/apache/ivy/core/deliver/DeliverOptions.java +++ b/src/java/org/apache/ivy/core/deliver/DeliverOptions.java @@ -55,7 +55,7 @@ public class DeliverOptions { /** * Returns an instance of DeliverOptions with options corresponding to default values taken from * the given settings. - * + * * @param settings * The settings to use to get default option values * @return a DeliverOptions instance ready to be used or customized @@ -74,6 +74,12 @@ public class DeliverOptions { /** * Creates an instance of DeliverOptions with all options explicitly set. + * @param status String + * @param pubDate Date + * @param pdrResolver PublishingDependencyRevisionResolver + * @param validate boolean + * @param resolveDynamicRevisions boolean + * @param confs String[] */ public DeliverOptions(String status, Date pubDate, PublishingDependencyRevisionResolver pdrResolver, boolean validate, @@ -93,7 +99,7 @@ public class DeliverOptions { * PublishingDependencyRevisionResolver can then do the delivering work for the dependency and * return the new (delivered) dependency info (with the delivered revision). Note that * PublishingDependencyRevisionResolver is only called for each direct dependency. - * + * * @return the pdrResolver that will be used during deliver */ public PublishingDependencyRevisionResolver getPdrResolver() { @@ -107,7 +113,8 @@ public class DeliverOptions { * PublishingDependencyRevisionResolver can then do the delivering work for the dependency and * return the new (delivered) dependency info (with the delivered revision). Note that * PublishingDependencyRevisionResolver is only called for each direct dependency. - * + * + * @param pdrResolver PublishingDependencyRevisionResolver * @return the instance of DeliverOptions on which the method has been called, for easy method * chaining */ @@ -155,7 +162,7 @@ public class DeliverOptions { /** * Returns the status to which the module should be delivered, or null if the current status * should be kept. - * + * * @return the status to which the module should be delivered */ public String getStatus() { @@ -165,7 +172,8 @@ public class DeliverOptions { /** * Sets the status to which the module should be delivered, use null if the current status * should be kept. - * + * + * @param status String * @return the instance of DeliverOptions on which the method has been called, for easy method * chaining */ @@ -176,7 +184,7 @@ public class DeliverOptions { /** * Returns the id of a previous resolve to use for delivering. - * + * * @return the id of a previous resolve */ public String getResolveId() { @@ -185,7 +193,7 @@ public class DeliverOptions { /** * Sets the id of a previous resolve to use for delivering. - * + * * @param resolveId * the id of a previous resolve * @return the instance of DeliverOptions on which the method has been called, for easy method @@ -199,7 +207,7 @@ public class DeliverOptions { /** * Return the configurations which must be delivered. Returns null if all configurations * has to be delivered. Attention: the returned array can contain wildcards! - * + * * @return the configurations to deliver */ public String[] getConfs() { @@ -208,7 +216,7 @@ public class DeliverOptions { /** * Sets the configurations to deliver. - * + * * @param confs * the configurations to deliver * @return the instance of DeliverOptions on which the method has been called, for easy method @@ -222,7 +230,7 @@ public class DeliverOptions { /** * Returns the branch with which the Ivy file should be delivered, or null if * branch info shouldn't be changed. - * + * * @return the branch with which the Ivy file should be delivered */ public String getPubBranch() { @@ -231,7 +239,7 @@ public class DeliverOptions { /** * Sets the branch with which the Ivy file should be delivered. - * + * * @param pubBranch * the branch with which the Ivy file should be delivered * @return the instance of DeliverOptions on which the method has been called, for easy method @@ -264,7 +272,6 @@ public class DeliverOptions { return "status=" + status + " pubdate=" + pubdate + " validate=" + validate + " resolveDynamicRevisions=" + resolveDynamicRevisions + " merge=" + merge + " resolveId=" + resolveId + " pubBranch=" + pubBranch; - } } diff --git a/src/java/org/apache/ivy/core/event/IvyEvent.java b/src/java/org/apache/ivy/core/event/IvyEvent.java index 18697a02..02ab78e4 100644 --- a/src/java/org/apache/ivy/core/event/IvyEvent.java +++ b/src/java/org/apache/ivy/core/event/IvyEvent.java @@ -27,15 +27,19 @@ import org.apache.ivy.core.module.id.ModuleRevisionId; import org.apache.ivy.util.StringUtils; /** + *

* The root of all ivy events Any ivy event knows which ivy instance triggered the event (the * source) and also has a name and a map of attributes. The name of the event represents the event * type, usually there is a one - one mapping between event names and IvyEvent subclass, even if - * this is not mandatory. Example: pre-resolve pre-resolve-dependency post-download The map of - * attributes is a Map from String keys to String values. It is especially useful to filter events, - * and to get some of their essential data in some context where access to Java types is not easy - * (in an ant build file, for example), Example: pre-resolve (organisation=foo, module=bar, - * revision=1.0, conf=default) post-download (organisation=foo, module=bar, revision=1.0, - * artifact=foo-test, type=jar, ext=jar) + * this is not mandatory. Example: pre-resolve pre-resolve-dependency post-download + *

+ *

+ * The map of attributes is a Map from String keys to String values. It is especially useful to + * filter events, and to get some of their essential data in some context where access to Java types + * is not easy (in an Ant build file, for example), Example: pre-resolve (organisation=foo, + * module=bar, revision=1.0, conf=default) post-download (organisation=foo, module=bar, + * revision=1.0, artifact=foo-test, type=jar, ext=jar) + *

*/ public class IvyEvent { private EventManager source; @@ -51,7 +55,7 @@ public class IvyEvent { /** * Should only be called during event object construction, since events should be immutable - * + * * @param key ditto * @param value ditto */ @@ -93,9 +97,9 @@ public class IvyEvent { } /** - * Returns the attributes of this event, as a Map(String->String) - * - * @return the attributes of this event, as a Map(String->String) + * Returns the attributes of this event, as a Map(String,String) + * + * @return the attributes of this event, as a Map(String,String) */ public Map getAttributes() { return new HashMap(attributes); diff --git a/src/java/org/apache/ivy/core/event/IvyEventFilter.java b/src/java/org/apache/ivy/core/event/IvyEventFilter.java index 6b0d87ea..ac9251f9 100644 --- a/src/java/org/apache/ivy/core/event/IvyEventFilter.java +++ b/src/java/org/apache/ivy/core/event/IvyEventFilter.java @@ -34,6 +34,7 @@ import org.apache.ivy.util.filter.OrFilter; * attribute values is done using the {@link PatternMatcher} used to construct this object. Here are * some examples: * + * * * * @@ -60,10 +61,10 @@ import org.apache.ivy.util.filter.OrFilter; * *
Filtering examples
expressioneffect
* Combination of these can be used, but no parentheses are supported right now, so only the default - * priority can be used. The priority order is this one: AND OR NOT = This means that artifact=foo - * AND ext=zip OR type=src will match event with artifact matching foo AND (ext matching zip OR type - * matching src) - * + * priority can be used. The priority order is this one: AND OR NOT = This means that + * artifact=foo AND ext=zip OR type=src will match event with artifact matching foo AND + * (ext matching zip OR type matching src) + * * @since 1.4 */ public class IvyEventFilter implements Filter { diff --git a/src/java/org/apache/ivy/core/module/descriptor/DefaultDependencyDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/DefaultDependencyDescriptor.java index 00fdea8f..10ec6846 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/DefaultDependencyDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/DefaultDependencyDescriptor.java @@ -57,7 +57,7 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { * descriptor in the system namespace. Note that exclude rules are not converted in system * namespace, because they aren't transformable (the name space hasn't the ability to convert * regular expressions). However, method doesExclude will work with system artifacts. - * + * * @param dd DependencyDescriptor * @param ns Namespace * @return DependencyDescriptor @@ -76,9 +76,10 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { * Transforms a dependency descriptor using the given transformer. Note that no namespace info * will be attached to the transformed dependency descriptor, so calling doesExclude is not * recommended (doesExclude only works when namespace is properly set) - * + * * @param dd DependencyDescriptor * @param t NamespaceTransformer + * @param fromSystem boolean * @return DefaultDependencyDescriptor */ public static DefaultDependencyDescriptor transformInstance(DependencyDescriptor dd, @@ -252,6 +253,7 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { * extending one). Both moduleConfiguration and requestedConfiguration are configurations of the * caller, the array returned is composed of the required configurations of the dependency * described by this descriptor. + *

*/ public String[] getDependencyConfigurations(String moduleConfiguration, String requestedConfiguration) { @@ -288,16 +290,22 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { * we do not handle special confs like *!sg or [cond]* in right hand * confs yet: it would require supporting parenthesis grouping in * configurations intersection interpretation - * - * for (Iterator it2 = depConfs.iterator(); it2.hasNext();) { String - * depConf = (String) it2.next(); if (depConf.startsWith("*")) { if - * (intersectedDepConf .indexOf("(" + depConf + ")") != -1) { - * intersectedDepConfs.add(intersectedDepConf); } else { - * intersectedDepConfs.add( "(" + intersectedDepConf + ")+(" + - * depConf + ")"); } } else if (intersectedDepConf.startsWith("*")) - * { if (depConf .indexOf("(" + intersectedDepConf + ")") != -1) { - * intersectedDepConfs.add(depConf); } else { - * intersectedDepConfs.add( depConf + "+" + intersectedDepConf); } } + * + * for (Iterator it2 = depConfs.iterator(); it2.hasNext();) { + * String depConf = (String) it2.next(); + * if (depConf.startsWith("*")) { + * if (intersectedDepConf .indexOf("(" + depConf + ")") != -1) { + * intersectedDepConfs.add(intersectedDepConf); + * } else { + * intersectedDepConfs.add( "(" + intersectedDepConf + ")+(" + depConf + ")"); + * } + * } else if (intersectedDepConf.startsWith("*")) { + * if (depConf .indexOf("(" + intersectedDepConf + ")") != -1) { + * intersectedDepConfs.add(depConf); + * } else { + * intersectedDepConfs.add( depConf + "+" + intersectedDepConf); + * } + * } * } */ } @@ -406,7 +414,7 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { /** * Replaces fallback patterns with correct values if fallback pattern exists. - * + * * @param pattern * pattern to look for * @param conf @@ -607,7 +615,7 @@ public class DefaultDependencyDescriptor implements DependencyDescriptor { } /** - * + * * @return true if this descriptor contains any exclusion rule */ public boolean canExclude() { diff --git a/src/java/org/apache/ivy/core/module/descriptor/DefaultModuleDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/DefaultModuleDescriptor.java index 1c039b65..b286bc2a 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/DefaultModuleDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/DefaultModuleDescriptor.java @@ -133,7 +133,7 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { * descriptor in the system namespace. Note that dependency exclude rules are not converted * in system namespace, because they aren't transformable (the name space hasn't the ability to * convert regular expressions) - * + * * @param md ModuleDescriptor * @param ns Namespace * @return ModuleDescriptor @@ -280,6 +280,9 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { /** * IMPORTANT : at least call setModuleRevisionId and setResolvedPublicationDate with instances * created by this constructor ! + * + * @param parser ModuleDescriptorParser + * @param res Resource */ public DefaultModuleDescriptor(ModuleDescriptorParser parser, Resource res) { this.parser = parser; @@ -361,7 +364,7 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { /** * Artifact configurations are not used since added artifact may not be entirely completed, so * its configurations data may not be accurate - * + * * @param conf ditto * @param artifact ditto */ @@ -427,6 +430,8 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { /** * Returns the configuration object with the given name in the current module descriptor, null * if not found. + * + * @param confName String */ public Configuration getConfiguration(String confName) { Configuration configuration = configurations.get(confName); @@ -599,7 +604,7 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { /** * regular expressions as explained in Pattern class may be used in ModuleId organisation and * name - * + * * @param moduleId ditto * @param matcher PatternMatcher * @param manager ConflictManager @@ -681,7 +686,7 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { } /** - * Throws an exception if the module descriptor is inconsistent For the moment, only extended + * Throws an exception if the module descriptor is inconsistent. For the moment, only extended * configurations existence and cycles are checked */ public void check() { @@ -781,8 +786,12 @@ public class DefaultModuleDescriptor implements ModuleDescriptor { } /** - * only works when namespace is properly set. The behaviour is not specified if namespace is not - * set + * Only works when namespace is properly set. The behaviour is not specified if namespace is + * not set. + * + * @param moduleConfigurations String[] + * @param artifactId ditto + * @return boolean */ public boolean doesExclude(String[] moduleConfigurations, ArtifactId artifactId) { if (namespace != null) { diff --git a/src/java/org/apache/ivy/core/module/descriptor/DependencyArtifactDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/DependencyArtifactDescriptor.java index 1ea78da4..f20080fb 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/DependencyArtifactDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/DependencyArtifactDescriptor.java @@ -27,44 +27,32 @@ import org.apache.ivy.util.extendable.ExtendableItem; */ public interface DependencyArtifactDescriptor extends ExtendableItem { /** - * Returns the dependency descriptor in which this dependency artifact descriptor is declared. - * * @return the dependency descriptor in which this dependency artifact descriptor is declared. */ public DependencyDescriptor getDependencyDescriptor(); /** - * Returns the name of the artifact asked - * - * @return + * @return the name of the artifact asked */ public String getName(); /** - * Returns the type of the artifact asked - * - * @return + * @return the type of the artifact asked */ public String getType(); /** - * Returns the ext of the artifact asked - * - * @return + * @return the ext of the artifact asked */ public String getExt(); /** - * Returns the url to look this artifact at - * - * @return + * @return the url to look this artifact up at */ public URL getUrl(); /** - * Returns the configurations of the module in which the artifact is asked - * - * @return an array of configuration names in which the artifact is asked + * @return an array of configuration names of the module in which the artifact is asked */ public String[] getConfigurations(); } diff --git a/src/java/org/apache/ivy/core/module/descriptor/DependencyDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/DependencyDescriptor.java index 13973d8b..880c0e32 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/DependencyDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/DependencyDescriptor.java @@ -34,11 +34,11 @@ import org.apache.ivy.util.extendable.ExtendableItem; *

*

* Then there is the dynamic constraint, which can either be the same as the default constraint, or - * the original dependency constraint when an Ivy file is delivered an published to a repository. - * This dynamic constraint is returned by {@link #getDynamicConstraintDependencyRevisionId()}, and - * corresponds to the revconstraint attribute in the Ivy file. In some resolve mode, - * this constraint can be used instead of the default dependency constraint when performing - * dependency resolution. + * the original dependency constraint when an Ivy file is delivered an published to a + * repository. This dynamic constraint is returned by + * {@link #getDynamicConstraintDependencyRevisionId()}, and corresponds to the + * revconstraint attribute in the Ivy file. In some resolve mode, this constraint can + * be used instead of the default dependency constraint when performing dependency resolution. *

*/ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { @@ -47,7 +47,7 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { /** * Used to indicate that this revision must be used in case of conflicts, independently of * conflicts manager. This only works for direct dependencies, and not transitive ones. - * + * * @return true if this dependency should be used, false if conflicts manager can do its work. */ boolean isForce(); @@ -57,7 +57,7 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { * that the revision may have its artifacts modified without revision change. When new artifacts * are published a new ivy file should also be published with a new publication date to indicate * to ivy that artifacts have changed and that they should be downloaded again. - * + * * @return true if this dependency is a changing one */ boolean isChanging(); @@ -68,14 +68,14 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { /** * Returns the constraint on dependency this descriptor represents. - * + * * @return the constraint on dependency. */ ModuleRevisionId getDependencyRevisionId(); /** * Returns the dynamic constraint on dependency this descriptor represents. - * + * * @return the dynamic constraint on dependency, or exact constraint if no dynamic constraint is * specified. */ @@ -111,7 +111,7 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { /** * Returns true if - * + * * @param moduleConfigurations ditto * @param artifactId ditto * @return boolean @@ -119,8 +119,6 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { boolean doesExclude(String[] moduleConfigurations, ArtifactId artifactId); /** - * Returns true if this descriptor contains any exclusion rule - * * @return true if this descriptor contains any exclusion rule */ public boolean canExclude(); @@ -129,7 +127,7 @@ public interface DependencyDescriptor extends ExtendableItem, InheritableItem { /** * Clones current dependency descriptor with another revision. - * + * * @param revision * the revision of the cloned dependency descriptor * @return the cloned dependency descriptor diff --git a/src/java/org/apache/ivy/core/module/descriptor/ExtendsDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/ExtendsDescriptor.java index 8b7456de..b953104f 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/ExtendsDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/ExtendsDescriptor.java @@ -24,12 +24,18 @@ import org.apache.ivy.core.module.id.ModuleRevisionId; */ public interface ExtendsDescriptor { - /** get the module revision id of the declared parent descriptor */ + /** + * get the module revision id of the declared parent descriptor + * + * @return ModuleRevisionId + */ public ModuleRevisionId getParentRevisionId(); /** * get the resolved revision id for {@link #getParentRevisionId}, see * {@link org.apache.ivy.core.module.descriptor.ModuleDescriptor#getResolvedModuleRevisionId()} + * + * @return ModuleRevisionId */ public ModuleRevisionId getResolvedParentRevisionId(); @@ -38,6 +44,8 @@ public interface ExtendsDescriptor { /** * If there is an explicit path to check for the parent descriptor, return it. Otherwise returns * null. + * + * @return String */ public String getLocation(); @@ -46,22 +54,34 @@ public interface ExtendsDescriptor { * info, description, configurations, * dependencies, and/or all. Ivy extensions may add support for * additional extends types. + * + * @return String[] */ public String[] getExtendsTypes(); - /** @return true if the all extend type is specified, implying all other types */ + /** + * @return true if the all extend type is specified, implying all other types + */ public boolean isAllInherited(); - /** @return true if parent info attributes are inherited (organisation, branch, revision, etc) */ + /** + * @return true if parent info attributes are inherited (organisation, branch, revision, etc) + */ public boolean isInfoInherited(); - /** @return true if parent description is inherited */ + /** + * @return true if parent description is inherited + */ public boolean isDescriptionInherited(); - /** @return true if parent configurations are inherited */ + /** + * @return true if parent configurations are inherited + */ public boolean areConfigurationsInherited(); - /** @return true if parent dependencies are inherited */ + /** + * @return true if parent dependencies are inherited + */ public boolean areDependenciesInherited(); public boolean isLocal(); diff --git a/src/java/org/apache/ivy/core/module/descriptor/ModuleDescriptor.java b/src/java/org/apache/ivy/core/module/descriptor/ModuleDescriptor.java index 1116d883..6b4a2a0f 100644 --- a/src/java/org/apache/ivy/core/module/descriptor/ModuleDescriptor.java +++ b/src/java/org/apache/ivy/core/module/descriptor/ModuleDescriptor.java @@ -46,35 +46,31 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, public static final String CALLER_ALL_CONFIGURATION = "all"; /** - * Returns true if this descriptor is a default one, i.e. one generated for a module not - * actually having one. - * - * @return boolean + * @return true if this descriptor is a default one, i.e. one generated for a module not + * actually having one. */ boolean isDefault(); ModuleRevisionId getModuleRevisionId(); /** - * The module revision id returned here is the resolved one, i.e. it is never a latest one. If - * the revision has not been resolved, a null revision should be returned by getRevision() of - * the returned ModuleRevisionId. This revision must be the same as the module descriptor - * resolved revision id unless no module descriptor is defined - * - * @return ModuleRevisionId + * @return the resolved module revision id; it is never the latest one. If the revision has not + * been resolved, a null revision should be returned by getRevision() of the returned + * ModuleRevisionId. This revision must be the same as the module descriptor resolved + * revision id unless no module descriptor is defined */ ModuleRevisionId getResolvedModuleRevisionId(); /** - * This method update the resolved module revision id + * This method updates the resolved module revision id * * @param revId ModuleRevisionId */ void setResolvedModuleRevisionId(ModuleRevisionId revId); /** - * Get the list of parent descriptors imported via an <extends> element. Only directly - * imported descriptors are included; the parent's parents are not included. + * @return the list of parent descriptors imported via an <extends> element. Only directly + * imported descriptors are included; the parent's parents are not included. */ ExtendsDescriptor[] getInheritedDescriptors(); @@ -88,9 +84,7 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, String getStatus(); /** - * May be null if unknown in the descriptor itself. - * - * @return The publication date or null when not known. + * @return the publication date or null when not known in the descriptor itself. */ Date getPublicationDate(); @@ -98,14 +92,14 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, * The publication date of the module revision should be the date at which it has been * published, i.e. in general the date of any of its published artifacts, since all published * artifact of a module should follow the same publishing cycle. + * + * @return Date */ Date getResolvedPublicationDate(); /** - * Returns all the configurations declared by this module as an array. This array is never empty - * (a 'default' conf is assumed when none is declared in the ivy file) - * - * @return all the configurations declared by this module as an array. + * @return all the configurations declared by this module as an array. This array is never empty + * (a 'default' conf is assumed when none is declared in the ivy file). */ Configuration[] getConfigurations(); @@ -116,27 +110,23 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, Artifact[] getArtifacts(String conf); /** - * Returns all artifacts of this module, excluding the artifact corresponding to the module - * descriptor. - * - * @return all published artifacts of this module + * @return all published artifacts of this module, excluding the artifact corresponding to the + * module descriptor. * @see #getMetadataArtifact() */ Artifact[] getAllArtifacts(); /** - * @return The dependencies of the module. If there is no dependencies return an empty array (non - * null) + * @return The dependencies of the module. If there are no dependencies return an empty array + * (non null) */ DependencyDescriptor[] getDependencies(); /** - * Returns true if the module described by this descriptor depends directly upon the given - * module descriptor - * * @param matcher VersionMatcher * @param md ModuleDescriptor - * @return boolean + * @return true if the module described by this descriptor depends directly upon the given + * module descriptor */ boolean dependsOn(VersionMatcher matcher, ModuleDescriptor md); @@ -147,18 +137,14 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, Configuration getConfiguration(String confName); /** - * Returns the conflict manager to use for the given ModuleId, or null if no - * specific conflict manager is associated with the given module id in this module descriptor. - * * @param id ModuleId - * @return ConflictManager + * @return the conflict manager to use for the given ModuleId, or null if no specific conflict + * manager is associated with the given module id in this module descriptor. */ ConflictManager getConflictManager(ModuleId id); /** - * Returns the licenses of the module described by this descriptor - * - * @return License[] + * @return the licenses of the module described by this descriptor */ License[] getLicenses(); @@ -175,92 +161,69 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, * * @param ivyFile * the destination ivy file + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ void toIvyFile(File ivyFile) throws ParseException, IOException; /** - * The ModuleDescriptorParser used to parse this module descriptor, null is no parser was used. - * - * @return ModuleDescriptorParser + * @return the ModuleDescriptorParser used to parse this module descriptor, null is no parser was used. */ ModuleDescriptorParser getParser(); /** - * The resource being the source of this module descriptor, null if no resource corresponds to - * this module descriptor - * - * @return Resource + * @return the resource being the source of this module descriptor, null if no resource + * corresponds to this module descriptor. */ Resource getResource(); /** - * Returns the Artifact representing this module descriptor itself. - *

* Even though the module descriptor is never described as a published artifact of a module in * the module descriptor itself, it is often useful to consider it as any other artifact of the * module. This method allows to access to the Artifact object representing this module * descriptor for this purpose. - *

* * @return the Artifact representing this module descriptor itself. */ Artifact getMetadataArtifact(); /** - * Returns true if this descriptor contains any exclusion rule - * - * @return true if this descriptor contains any exclusion rule + * @return true if this descriptor contains any exclusion rule. */ boolean canExclude(); /** - * Returns true if an exclude rule of this module attached to any of the given configurations - * matches the given artifact id, and thus exclude it - * * @param moduleConfs String[] * @param artifactId ditto - * @return boolean + * @return true if an exclude rule of this module attached to any of the given configurations + * matches the given artifact id, and thus exclude it */ boolean doesExclude(String[] moduleConfs, ArtifactId artifactId); /** - * Returns an array of all the exclude rules this module descriptor currently holds. Module - * Descriptor exclude rules are used to exclude (usually transitive) dependencies for the whole - * module. + * Module Descriptor exclude rules are used to exclude (usually transitive) dependencies for the + * whole module. * - * @return an array of {@link ExcludeRule} this module descriptor holds + * @return an array of all {@link ExcludeRule} this module descriptor currently holds. */ public ExcludeRule[] getAllExcludeRules(); /** - * Returns all the dependency descriptor mediators used by this {@link ModuleDescriptor}, as an - * instance of {@link ModuleRules}. - *

- * All rules in the {@link ModuleRules} object returned are {@link DependencyDescriptorMediator} - * . - *

- * - * @return all the dependency descriptor mediators used by this {@link ModuleDescriptor}. + * @return all the {@link DependencyDescriptorMediator}s used by this + * {@link ModuleDescriptor}, as an instance of {@link ModuleRules}. */ public ModuleRules/* */getAllDependencyDescriptorMediators(); /** - * Returns the list of xml namespaces used by extra attributes, as Map from prefix to namespace - * URIs. - *

- * The returned list is never null, it is empty when no extra attribute is used or - * if extra attributes are used without xml namespaces - *

- * * @return the list of xml namespaces used by extra attributes, as Map from prefix to namespace - * URIs. + * URIs. The returned list is never null, it is empty when no extra attribute is used or + * if extra attributes are used without xml namespaces */ Map getExtraAttributesNamespaces(); /** - * Returns the custom info provided in the info tag. All the tags except the description are - * given. The key is the name of the tag, the value is its content.
- * + * @return the custom info provided in the info tag. All the tags except the description are + * given. The key is the name of the tag, the value is its content. * @deprecated this method is not returning the full content of the extra info: to get the full * structure of the extra infos, use getExtraInfos() */ @@ -268,27 +231,23 @@ public interface ModuleDescriptor extends ExtendableItem, ArtifactInfo, Map getExtraInfo(); /** - * Returns a list of extras infos (tag name, attributes and content). All the tags except the - * description are given. - * * @since 2.4.0 - * @return List<ExtraInfoHolder> + * @return a list of extras infos (tag name, attributes and content). All the tags except the + * description are given. */ List getExtraInfos(); /** - * Returns content from first extrainfo matching with given tag name - * * @since 2.4.0 - * @return ditto + * @param tagName String + * @return content from first extrainfo matching with given tag name. */ String getExtraInfoContentByTagName(String tagName); /** - * Returns first extrainfo matching with given tag name - * * @since 2.4.0 - * @return ExtraInfoHolder + * @param tagName String + * @return first extrainfo matching with given tag name. */ ExtraInfoHolder getExtraInfoByTagName(String tagName); } diff --git a/src/java/org/apache/ivy/core/module/id/ArtifactId.java b/src/java/org/apache/ivy/core/module/id/ArtifactId.java index 0991c1f0..a1747384 100644 --- a/src/java/org/apache/ivy/core/module/id/ArtifactId.java +++ b/src/java/org/apache/ivy/core/module/id/ArtifactId.java @@ -19,7 +19,7 @@ package org.apache.ivy.core.module.id; /** * Identifies an artifact in a module, without revision information - * + * * @see org.apache.ivy.core.module.id */ public class ArtifactId { @@ -38,6 +38,8 @@ public class ArtifactId { * The name of the artifact. * @param type * The type of the artifact. + * @param ext + * The name extension of the artifact. */ public ArtifactId(ModuleId mid, String name, String type, String ext) { this.mid = mid; diff --git a/src/java/org/apache/ivy/core/module/id/MatcherLookup.java b/src/java/org/apache/ivy/core/module/id/MatcherLookup.java index c1fa6ad1..714643a7 100644 --- a/src/java/org/apache/ivy/core/module/id/MatcherLookup.java +++ b/src/java/org/apache/ivy/core/module/id/MatcherLookup.java @@ -33,24 +33,22 @@ import org.apache.ivy.plugins.matcher.PatternMatcher; * matcher's attributes. When matcher is looked up against specific module, the key is recreated * from module's attributes. *

- *

* The lookup doesn't target to speed up lookup for non exact pattern matcher. All non exact * matchers are placed in non-keyed collection. - *

*

+ *

* At lookup for matchers against specific module, all non exact pattern matchers are iterated to * match with module attributes, and exact pattern matchers binding to the same key will also * iterated to match with module attributes. - *

*

+ *

* If there are much more exact pattern matchers than non exact pattern matchers, the matcher lookup * speed can benefit from this class significantly. A quick example could be user declares lots of * dependencyOverrides which are typically exact pattern matchers. - *

*

+ *

* If there are balanced exact and non exact pattern matchers, the matcher lookup speed doesn't hurt * by this class. - *

*

*/ public class MatcherLookup { @@ -65,12 +63,12 @@ public class MatcherLookup { /** * Add matcher. - * + * * If matcher is exact pattern matcher, it will be associated with a key and placed in keyed * collection. - * + * * If matcher is not exact pattern matcher, it will be placed into non-keyed collection - * + * * @param matcher MapMatcher */ public void add(MapMatcher matcher) { @@ -88,12 +86,10 @@ public class MatcherLookup { } /** - * Get a list of matchers which can apply to module with specified attributes - * * @param attrs * A map of attributes that matcher should match. - * - * @return list A list of candidate matchers that matches specified attributes + * + * @return a list of matchers that can apply to module withs specified attributes */ public List get(Map attrs) { List matchers = new ArrayList(); @@ -131,7 +127,7 @@ public class MatcherLookup { /** * Create a key from specified attributes - * + * * @param attrs * A map of attributes * @return key object diff --git a/src/java/org/apache/ivy/core/publish/PublishEngine.java b/src/java/org/apache/ivy/core/publish/PublishEngine.java index d6a79041..a43240cb 100644 --- a/src/java/org/apache/ivy/core/publish/PublishEngine.java +++ b/src/java/org/apache/ivy/core/publish/PublishEngine.java @@ -73,6 +73,13 @@ public class PublishEngine { * reports. The extra artifacts array can be null (= no extra artifacts), and if non null only * the name, type, ext url and extra attributes of the artifacts are really used. Other methods * can return null safely. + * + * @param mrid ModuleRevisionId + * @param srcArtifactPattern a Collection of String + * @param resolverName String + * @param options PublishOptions + * @return Collection<Artifact> + * @throws IOException if something goes wrong */ public Collection publish(ModuleRevisionId mrid, Collection srcArtifactPattern, String resolverName, PublishOptions options) diff --git a/src/java/org/apache/ivy/core/report/ConfigurationResolveReport.java b/src/java/org/apache/ivy/core/report/ConfigurationResolveReport.java index 38296df7..47fa680e 100644 --- a/src/java/org/apache/ivy/core/report/ConfigurationResolveReport.java +++ b/src/java/org/apache/ivy/core/report/ConfigurationResolveReport.java @@ -78,11 +78,15 @@ public class ConfigurationResolveReport { } /** - * Check if the set of dependencies has changed since the previous execution of a resolution.
+ * Check if the set of dependencies has changed since the previous execution of a resolution. + *

* This function use the report file found in the cache. So the function must be called before - * the new report is serialized there.
This function also use the internal dependencies - * that must already be filled. This function might be 'heavy' because it may have to parse the - * previous report. + * the new report is serialized there. + *

+ *

+ * This function also use the internal dependencies that must already be filled. This function + * might be 'heavy' because it may have to parse the previous report. + *

*/ public void checkIfChanged() { ResolutionCacheManager cache = resolveEngine.getSettings().getResolutionCacheManager(); @@ -109,6 +113,7 @@ public class ConfigurationResolveReport { /** * @pre checkIfChanged has been called. + * @return boolean */ public boolean hasChanged() { return hasChanged; @@ -117,7 +122,7 @@ public class ConfigurationResolveReport { /** * Returns all non evicted and non error dependency mrids The returned set is ordered so that a * dependency will always be found before their own dependencies - * + * * @return all non evicted and non error dependency mrids */ public Set getModuleRevisionIds() { @@ -235,7 +240,7 @@ public class ConfigurationResolveReport { /** * gives all the modules ids concerned by this report, from the most dependent to the least one - * + * * @return a list of ModuleId */ public List getModuleIds() { @@ -278,7 +283,7 @@ public class ConfigurationResolveReport { /** * Get every report on the download requests. - * + * * @return the list of reports, never null */ public ArtifactDownloadReport[] getAllArtifactsReports() { @@ -288,7 +293,7 @@ public class ConfigurationResolveReport { /** * Get the report on the download requests. The list of download report can be restricted to a * specific download status, and also remove the download report for the evicted modules. - * + * * @param downloadStatus * the status of download to retrieve. Set it to null for no restriction * on the download status @@ -321,7 +326,7 @@ public class ConfigurationResolveReport { /** * Get the report on the successful download requests with the evicted modules - * + * * @return the list of reports, never null */ public ArtifactDownloadReport[] getDownloadedArtifactsReports() { @@ -330,7 +335,7 @@ public class ConfigurationResolveReport { /** * Get the report on the failed download requests with the evicted modules - * + * * @return the list of reports, never null */ public ArtifactDownloadReport[] getFailedArtifactsReports() { diff --git a/src/java/org/apache/ivy/core/report/DownloadStatus.java b/src/java/org/apache/ivy/core/report/DownloadStatus.java index f0364c26..db5fab5a 100644 --- a/src/java/org/apache/ivy/core/report/DownloadStatus.java +++ b/src/java/org/apache/ivy/core/report/DownloadStatus.java @@ -38,7 +38,8 @@ public final class DownloadStatus { /** * Returns the {@link DownloadStatus} corresponding to the given String representation. - * + * + * @param status String * @return the {@link DownloadStatus} corresponding to the given String representation. * @throws IllegalArgumentException * if the given String does not correspond to any {@link DownloadStatus}. diff --git a/src/java/org/apache/ivy/core/report/ResolveReport.java b/src/java/org/apache/ivy/core/report/ResolveReport.java index 0fb05f09..01be7487 100644 --- a/src/java/org/apache/ivy/core/report/ResolveReport.java +++ b/src/java/org/apache/ivy/core/report/ResolveReport.java @@ -128,7 +128,7 @@ public class ResolveReport { /** * Get every report on the download requests. - * + * * @return the list of reports, never null */ public ArtifactDownloadReport[] getFailedArtifactsReports() { @@ -138,7 +138,7 @@ public class ResolveReport { /** * Get every report on the download requests. - * + * * @return the list of reports, never null */ public ArtifactDownloadReport[] getAllArtifactsReports() { @@ -148,7 +148,7 @@ public class ResolveReport { /** * Get the report on the download requests. The list of download report can be restricted to a * specific download status, and also remove the download report for the evicted modules. - * + * * @param downloadStatus * the status of download to retrieve. Set it to null for no restriction * on the download status @@ -184,7 +184,11 @@ public class ResolveReport { } } - /** Can only be called if checkIfChanged has been called */ + /** + * Can only be called if checkIfChanged has been called + * + * @return boolean + */ public boolean hasChanged() { for (ConfigurationResolveReport report : confReports.values()) { if (report.hasChanged()) { @@ -245,7 +249,7 @@ public class ResolveReport { /** * Returns the list of all dependencies concerned by this report as a List of IvyNode ordered * from the more dependent to the least one - * + * * @return The list of all dependencies. */ public List getDependencies() { @@ -255,7 +259,7 @@ public class ResolveReport { /** * Returns the list of all artifacts which should be downloaded per this resolve To know if the * artifact have actually been downloaded use information found in ConfigurationResolveReport. - * + * * @return The list of all artifacts. */ public List getArtifacts() { @@ -264,7 +268,7 @@ public class ResolveReport { /** * gives all the modules ids concerned by this report, from the most dependent to the least one - * + * * @return a list of ModuleId */ public List getModuleIds() { @@ -305,7 +309,7 @@ public class ResolveReport { * This only includes artifacts actually downloaded to cache (DownloadStatus.SUCCESSFUL), and * not artifacts already in cache or used at their original location. *

- * + * * @return The total size of downloaded artifacts, in bytes. */ public long getDownloadSize() { @@ -319,7 +323,7 @@ public class ResolveReport { /** * Get every configuration which extends the specified one. The returned list also includes the * specified one. - * + * * @param extended String * @return String[] */ diff --git a/src/java/org/apache/ivy/core/resolve/IvyNode.java b/src/java/org/apache/ivy/core/resolve/IvyNode.java index 4cac6c7a..a26146fb 100644 --- a/src/java/org/apache/ivy/core/resolve/IvyNode.java +++ b/src/java/org/apache/ivy/core/resolve/IvyNode.java @@ -132,7 +132,16 @@ public class IvyNode implements Comparable { /** * After the call node may be discarded. To avoid using discarded node, make sure to get the - * real node after the call IvyNode node = ... node.loadData(); node = node.getRealNode(); ... + * real node after the call + * IvyNode node = ... node.loadData(); node = node.getRealNode(); ... + * + * @param rootModuleConf String + * @param parent IvyNode + * @param parentConf String + * @param conf String + * @param shouldBePublic boolean + * @param usage IvyNodeUsage + * @return boolean */ public boolean loadData(String rootModuleConf, IvyNode parent, String parentConf, String conf, boolean shouldBePublic, IvyNodeUsage usage) { @@ -312,7 +321,7 @@ public class IvyNode implements Comparable { * Load the dependencies of the current node *

* The resulting collection of nodes may have some configuration to load - * + * * @param rootModuleConf * the requested configuration of the root module * @param conf @@ -515,7 +524,7 @@ public class IvyNode implements Comparable { /** * returns the required configurations from the given node - * + * * @param in IvyNode * @param inConf ditto * @return array of configuration names @@ -537,7 +546,7 @@ public class IvyNode implements Comparable { /** * returns all the current required configurations of the node - * + * * @return array of configuration names */ public String[] getRequiredConfigurations() { @@ -564,7 +573,7 @@ public class IvyNode implements Comparable { /** * Returns the configurations of the dependency required in a given root module configuration. - * + * * @param rootModuleConf String * @return array of configuration names */ @@ -620,7 +629,7 @@ public class IvyNode implements Comparable { /** * Returns the root module configurations in which this dependency is required - * + * * @return array of configuration names */ public String[] getRootModuleConfigurations() { @@ -630,7 +639,7 @@ public class IvyNode implements Comparable { /** * Returns the root module configurations in which this dependency is required - * + * * @return {@link Set} of configuration names */ public Set getRootModuleConfigurationsSet() { @@ -675,7 +684,7 @@ public class IvyNode implements Comparable { /** * Finds and returns a path in callers from the given module id to the current node - * + * * @param from * the module id to start the path from * @return a collection representing the path, starting with the from node, followed by the list @@ -707,7 +716,7 @@ public class IvyNode implements Comparable { /** * Update data in this node from data of the given node, for the given root module * configuration. - * + * * @param node * the source node from which data should be copied * @param rootModuleConf @@ -748,7 +757,7 @@ public class IvyNode implements Comparable { /** * Returns all the artifacts of this dependency required in all the root module configurations - * + * * @return array of {@link Artifact}s */ public Artifact[] getAllArtifacts() { @@ -762,7 +771,7 @@ public class IvyNode implements Comparable { /** * Returns all the artifacts of this dependency required in the root module configurations in * which the node is not evicted nor blacklisted - * + * * @param artifactFilter Filter * @return array of {@link Artifact}s */ @@ -780,7 +789,7 @@ public class IvyNode implements Comparable { /** * Returns the artifacts of this dependency required in the configurations themselves required * in the given root module configuration - * + * * @param rootModuleConf String * @return array of {@link Artifact}s */ @@ -995,7 +1004,7 @@ public class IvyNode implements Comparable { /** * Returns the last modified timestamp of the module represented by this Node, or 0 if the last * modified timestamp is currently unknown (module not loaded) - * + * * @return the last modified timestamp of the module represented by this Node */ public long getLastModified() { @@ -1085,7 +1094,13 @@ public class IvyNode implements Comparable { // EVICTION MANAGEMENT // ///////////////////////////////////////////////////////////////////////////// - /** A copy of the set of resolved nodes (real nodes) */ + /** + * A copy of the set of resolved nodes (real nodes) + * + * @param moduleId ditto + * @param rootModuleConf String + * @return Set<IvyNode> + */ public Set getResolvedNodes(ModuleId moduleId, String rootModuleConf) { return eviction.getResolvedNodes(moduleId, rootModuleConf); } @@ -1190,7 +1205,7 @@ public class IvyNode implements Comparable { /** * Returns a collection of Nodes in conflict for which conflict has been detected but conflict * resolution hasn't been done yet - * + * * @param rootModuleConf ditto * @param mid * the module id for which pending conflicts should be found @@ -1217,7 +1232,7 @@ public class IvyNode implements Comparable { * implementation which use a best effort strategy to find compatible dependency set, like * {@link LatestCompatibleConflictManager} *

- * + * * @param bdata * the root module configuration in which the node should be blacklisted */ @@ -1255,10 +1270,10 @@ public class IvyNode implements Comparable { *

* A blacklisted node should be considered as if it doesn't even exist on the repository. *

- * + * * @param rootModuleConf * the root module conf for which we'd like to know if the node is blacklisted - * + * * @return true if this node is blacklisted int he given root module conf, false otherwise * @see #blacklist(IvyNodeBlacklist) */ @@ -1268,7 +1283,7 @@ public class IvyNode implements Comparable { /** * Indicates if this node has been blacklisted in all root module configurations. - * + * * @return true if this node is blacklisted in all root module configurations, false otherwise * @see #blacklist(IvyNodeBlacklist) */ @@ -1287,7 +1302,7 @@ public class IvyNode implements Comparable { /** * Returns the blacklist data of this node in the given root module conf, or null * if this node is not blacklisted in this root module conf. - * + * * @param rootModuleConf * the root module configuration to consider * @return the blacklist data if any @@ -1308,7 +1323,7 @@ public class IvyNode implements Comparable { * given root module conf which has a dependency descriptor with transitive == true, then it * returns true. Otherwise it returns false. *

- * + * * @param rootModuleConf * the root module configuration to consider * @return true if there is any merged usage with transitive dd, false otherwise. diff --git a/src/java/org/apache/ivy/core/resolve/IvyNodeCallers.java b/src/java/org/apache/ivy/core/resolve/IvyNodeCallers.java index e5f5966a..f9c6d57d 100644 --- a/src/java/org/apache/ivy/core/resolve/IvyNodeCallers.java +++ b/src/java/org/apache/ivy/core/resolve/IvyNodeCallers.java @@ -154,6 +154,7 @@ public class IvyNodeCallers { * @param rootModuleConf ditto * @param callerNode IvyNode * @param callerConf ditto + * @param requestedConf ditto * @param dependencyConfs * '*' must have been resolved * @param dd @@ -251,7 +252,7 @@ public class IvyNodeCallers { /** * Returns true if ALL callers exclude the given artifact in the given root module conf - * + * * @param rootModuleConf ditto * @param artifact Artifact * @return boolean diff --git a/src/java/org/apache/ivy/core/resolve/IvyNodeEviction.java b/src/java/org/apache/ivy/core/resolve/IvyNodeEviction.java index 940dfa18..3524f21f 100644 --- a/src/java/org/apache/ivy/core/resolve/IvyNodeEviction.java +++ b/src/java/org/apache/ivy/core/resolve/IvyNodeEviction.java @@ -54,7 +54,7 @@ public class IvyNodeEviction { /** * Creates a new object containing the eviction data of an {@link IvyNode}. - * + * * @param rootModuleConf * the root module configuration * @param parent @@ -73,7 +73,7 @@ public class IvyNodeEviction { /** * Creates a new object containing the eviction data of an {@link IvyNode}. - * + * * @param rootModuleConf * the root module configuration * @param parent @@ -197,6 +197,8 @@ public class IvyNodeEviction { } /** + * @param mid ModuleId + * @param rootModuleConf String * @return A copy of the set of resolved nodes (real nodes) */ public Set getResolvedNodes(ModuleId mid, String rootModuleConf) { @@ -337,7 +339,7 @@ public class IvyNodeEviction { /** * Returns null if this node has only be evicted transitively, or the the collection of selected * nodes if it has been evicted by other selected nodes - * + * * @return Collection<IvyNode> */ public Collection getAllEvictingNodes() { @@ -385,7 +387,7 @@ public class IvyNodeEviction { * Returns the eviction data for this node if it has been previously evicted in the root, null * otherwise (if it hasn't been evicted in root) for the given rootModuleConf. Note that this * method only works if conflict resolution has already be done in all the ancestors. - * + * * @param rootModuleConf ditto * @param ancestor IvyNode * @return EvictionData diff --git a/src/java/org/apache/ivy/core/resolve/ResolveEngine.java b/src/java/org/apache/ivy/core/resolve/ResolveEngine.java index 7c0a11a5..8356f167 100644 --- a/src/java/org/apache/ivy/core/resolve/ResolveEngine.java +++ b/src/java/org/apache/ivy/core/resolve/ResolveEngine.java @@ -76,7 +76,7 @@ import org.apache.ivy.util.filter.Filter; * {@link #resolve(URL)} which allow to simply resolve dependencies of a single module descriptor, * or more complete one, like the {@link #resolve(ModuleDescriptor, ResolveOptions)} which allows to * provide options to the resolution engine. - * + * * @see ResolveOptions */ public class ResolveEngine { @@ -92,7 +92,7 @@ public class ResolveEngine { /** * Constructs a ResolveEngine. - * + * * @param settings * the settings to use to configure the engine. Must not be null. * @param eventManager @@ -112,7 +112,7 @@ public class ResolveEngine { /** * Returns the currently configured dictator resolver, which when non null is used in place of * any specified resolver in the {@link IvySettings} - * + * * @return the currently configured dictator resolver, may be null. */ public DependencyResolver getDictatorResolver() { @@ -122,7 +122,7 @@ public class ResolveEngine { /** * Sets a dictator resolver, which is used in place of regular dependency resolver for * subsequent dependency resolution by this engine. - * + * * @param dictatorResolver * the dictator resolver to use in this engine, null if regular settings should used */ @@ -142,6 +142,13 @@ public class ResolveEngine { /** * Resolves the module identified by the given mrid with its dependencies if transitive is set * to true. + * + * @param mrid ModuleRevisionId + * @param options ResolveOptions + * @param changing boolean + * @return ResolveReport + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public ResolveReport resolve(final ModuleRevisionId mrid, ResolveOptions options, boolean changing) throws ParseException, IOException { @@ -176,6 +183,12 @@ public class ResolveEngine { /** * Resolve dependencies of a module described by an ivy file. + * + * @param ivySource URL + * @param options ResolveOptions + * @return ResolveReport + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public ResolveReport resolve(URL ivySource, ResolveOptions options) throws ParseException, IOException { @@ -197,6 +210,11 @@ public class ResolveEngine { /** * Resolve dependencies of a module described by a module descriptor. + * @param md ModuleDescriptor + * @param options ResolveOptions + * @return ResolveReport + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public ResolveReport resolve(ModuleDescriptor md, ResolveOptions options) throws ParseException, IOException { @@ -434,9 +452,10 @@ public class ResolveEngine { * It is possible to track the progression of the download using classical ivy progress * monitoring feature (see addTransferListener). *

- * + * * @param artifact * the artifact to download + * @param options DownloadOptions * @return a report concerning the download * @see #download(ArtifactOrigin, DownloadOptions) */ @@ -449,7 +468,7 @@ public class ResolveEngine { /** * Locates an artifact in dependency resolvers, and return its location if it can be located and * actually exists, or an unknown {@link ArtifactOrigin} in other cases. - * + * * @param artifact * the artifact to locate. * @return the artifact location, should be tested with @@ -475,9 +494,10 @@ public class ResolveEngine { * It is possible to track the progression of the download using classical ivy progress * monitoring feature (see addTransferListener). *

- * + * * @param origin * the artifact origin to materialize + * @param options DownloadOptions * @return a report concerning the download * @see #download(Artifact, DownloadOptions) * @see #locate(Artifact) @@ -492,7 +512,7 @@ public class ResolveEngine { * Resolve the dependencies of a module without downloading corresponding artifacts. The module * to resolve is given by its ivy file URL. This method requires appropriate configuration of * the ivy instance, especially resolvers. - * + * * @param ivySource * url of the ivy file to use for dependency resolving * @param options @@ -517,7 +537,7 @@ public class ResolveEngine { *

* The IvyNodes are ordered from the most dependent to the less dependent, so that * an IvyNode is always found in the list after all IvyNode depending directly on it. - * + * * @param md * the descriptor of the module for which we want to get dependencies - must not be * null @@ -817,7 +837,7 @@ public class ResolveEngine { /** * Returns true if we've already fetched the dependencies for this node and configuration - * + * * @param node * node to check * @param conf @@ -847,11 +867,12 @@ public class ResolveEngine { /** * Resolves conflict for the given node in the given ancestor. This method do conflict * resolution in ancestor parents recursively, unless not necessary. - * + * * @param node * the node for which conflict resolution should be done * @param ancestor * the ancestor in which the conflict resolution should be done + * @param conf String * @param toevict * a collection of IvyNode to evict (as computed by conflict resolution in * descendants of ancestor) @@ -1033,7 +1054,7 @@ public class ResolveEngine { /** * Compute possible conflicts for a node, in the context of an ancestor (a node which has a * dependency - direct or indirect - on the node for which conflicts should be computed. - * + * * @param node * the node for which conflicts should be computed * @param ancestor @@ -1159,7 +1180,7 @@ public class ResolveEngine { * The mediated dependency descriptor must return the actually requested module revision id when * the method {@link DependencyDescriptor#getDependencyRevisionId()} is called. *

- * + * * @param dd * the dependency descriptor for which the requested module revision id should be * returned diff --git a/src/java/org/apache/ivy/core/resolve/ResolveOptions.java b/src/java/org/apache/ivy/core/resolve/ResolveOptions.java index f71b0159..c492a4ed 100644 --- a/src/java/org/apache/ivy/core/resolve/ResolveOptions.java +++ b/src/java/org/apache/ivy/core/resolve/ResolveOptions.java @@ -29,7 +29,7 @@ import org.apache.ivy.util.filter.FilterHelper; /** * A set of options used during resolve related tasks - * + * * @see ResolveEngine */ public class ResolveOptions extends LogOptions { @@ -153,7 +153,7 @@ public class ResolveOptions extends LogOptions { /** * Returns the resolve mode to use, or null to use settings configured resolve * mode. - * + * * @return the resolve mode to use. */ public String getResolveMode() { @@ -169,7 +169,8 @@ public class ResolveOptions extends LogOptions { * Indicates if the configurations use a special configuration * , *(private) or *(public). When * special configurations are used, you must have the module descriptor in order to get the list * of configurations. - * + * + * @return boolean * @see #getConfs() * @see #getConfs(ModuleDescriptor) */ @@ -185,6 +186,7 @@ public class ResolveOptions extends LogOptions { /** * @pre can only be called if useSpecialConfs()==false. When it is true, you have to provide a * module descriptor so that configurations can be resolved. + * @return String[] * @see #getConfs(ModuleDescriptor) */ public String[] getConfs() { @@ -197,10 +199,11 @@ public class ResolveOptions extends LogOptions { /** * Get the asked confs. Special confs (like *) use the moduleDescriptor to find the values * - * + * * @param md * Used to get the exact values for special confs. - * */ + * @return String[] + */ public String[] getConfs(ModuleDescriptor md) { // TODO add isInline, in that case, replace * by *(public). return ConfigurationUtils.replaceWildcards(confs, md); diff --git a/src/java/org/apache/ivy/core/resolve/VisitNode.java b/src/java/org/apache/ivy/core/resolve/VisitNode.java index c38bce19..b5171b96 100644 --- a/src/java/org/apache/ivy/core/resolve/VisitNode.java +++ b/src/java/org/apache/ivy/core/resolve/VisitNode.java @@ -40,11 +40,11 @@ import org.apache.ivy.util.Checks; * dependency graph following the dependencies, thus the same node can be visited several times, if * it is requested from several module. In this case you will have one VisitNode per parent and per * root module configuration. Thus VisitNode stores data specific to the visit: - *
    - *
  • parent
    • the node from which the visit is occurring - *
  • parentConf
    • the configuration of the parent in which this node is visited - *
  • rootModuleConf
    • the configuration of the root module which is currently resolved - *
+ *
+ *
parent
the node from which the visit is occurring
+ *
parentConf
the configuration of the parent in which this node is visited
+ *
rootModuleConf
the configuration of the root module which is currently resolved
+ *
*/ public class VisitNode { /** @@ -152,7 +152,7 @@ public class VisitNode { /** * Get an ordered collection with the nodes from the root to this node - * + * * @return Collection<VisitNode> */ public Collection getPath() { @@ -211,7 +211,7 @@ public class VisitNode { /** * Returns true if the current dependency descriptor is transitive and the parent configuration * is transitive. Otherwise returns false. - * + * * @return true if current node is transitive and the parent configuration is transitive. */ public boolean isTransitive() { @@ -255,7 +255,7 @@ public class VisitNode { * resolved to an existing node in the graph, we will return the existing node, and not the one * originally used which is about to be discarded, since it's not possible to have in the graph * two nodes for the same ModuleRevisionId - * + * * @return the 'real' node currently visited. */ public IvyNode getRealNode() { @@ -313,7 +313,7 @@ public class VisitNode { /** * Returns a VisitNode for the given node. The given node must be a representation of the same * module (usually in another revision) as the one visited by this node. - * + * * @param node * the node to visit * @return a VisitNode for the given node @@ -413,7 +413,7 @@ public class VisitNode { /** * Returns true if this node can already be found in the path - * + * * @return boolean */ public boolean isCircular() { @@ -461,7 +461,7 @@ public class VisitNode { /** * Marks the current node as evicted by the the given selected IvyNodes, in the given parent and * root module configuration, with the given {@link ConflictManager} - * + * * @param parent * the VisitNode in which eviction has been made * @param conflictMgr diff --git a/src/java/org/apache/ivy/core/retrieve/RetrieveEngine.java b/src/java/org/apache/ivy/core/retrieve/RetrieveEngine.java index 0e0d68c0..4822e897 100644 --- a/src/java/org/apache/ivy/core/retrieve/RetrieveEngine.java +++ b/src/java/org/apache/ivy/core/retrieve/RetrieveEngine.java @@ -71,7 +71,12 @@ public class RetrieveEngine { * localCacheDirectory to determine an ivy report file, used as input for the copy If such a * file does not exist for any conf (resolve has not been called before ?) then an * IllegalStateException is thrown and nothing is copied. - * + * + * @param mrid ModuleRevisionId + * @param destFilePattern String + * @param options RetrieveOptions + * @return int + * @throws IOException if something goes wrong * @deprecated Use * {@link #retrieve(org.apache.ivy.core.module.id.ModuleRevisionId, RetrieveOptions)} * instead @@ -485,7 +490,7 @@ public class RetrieveEngine { /** * The returned comparator should consider greater the artifact which gains the conflict battle. * This is used only during retrieve... prefer resolve conflict manager to resolve conflicts. - * + * * @return Comparator<ArtifactDownloadReport> */ private Comparator getConflictResolvingPolicy() { diff --git a/src/java/org/apache/ivy/core/retrieve/RetrieveReport.java b/src/java/org/apache/ivy/core/retrieve/RetrieveReport.java index bff2007e..6dcb9fd5 100644 --- a/src/java/org/apache/ivy/core/retrieve/RetrieveReport.java +++ b/src/java/org/apache/ivy/core/retrieve/RetrieveReport.java @@ -38,6 +38,8 @@ public class RetrieveReport { /** * Returns the root directory to where the artifacts are retrieved. + * + * @return File */ public File getRetrieveRoot() { return retrieveRoot; @@ -68,6 +70,8 @@ public class RetrieveReport { /** * Returns a collection of File objects who were actually copied during the retrieve * process. + * + * @return Collection<File> */ public Collection getCopiedFiles() { return new ArrayList(copiedFiles); @@ -76,6 +80,8 @@ public class RetrieveReport { /** * Returns a collection of File objects who were actually copied during the retrieve * process. + * + * @return Collection<File> */ public Collection getUpToDateFiles() { return new ArrayList(upToDateFiles); @@ -84,6 +90,8 @@ public class RetrieveReport { /** * Returns a collection of File objects who were retrieved during the retrieve process. * This is the union of the files being copied and the files that were up-to-date. + * + * @return Collection<File> */ public Collection getRetrievedFiles() { Collection result = new ArrayList(upToDateFiles.size() + copiedFiles.size()); @@ -94,6 +102,8 @@ public class RetrieveReport { /** * Get the mapping between the copied files and their corresponding download report + * + * @return Map<File,ArtifactDownloadReport> */ public Map getDownloadReport() { return downloadReport; diff --git a/src/java/org/apache/ivy/core/search/SearchEngine.java b/src/java/org/apache/ivy/core/search/SearchEngine.java index 537566f7..3fde2637 100644 --- a/src/java/org/apache/ivy/core/search/SearchEngine.java +++ b/src/java/org/apache/ivy/core/search/SearchEngine.java @@ -50,10 +50,10 @@ public class SearchEngine { /** * Returns an empty array when no token values are found. - * + * * @param token * ditto - * @param otherTokenValues + * @param otherTokenValues Map * @return String[] */ public String[] listTokenValues(String token, Map otherTokenValues) { @@ -177,10 +177,9 @@ public class SearchEngine { *

* ModuleId are returned in the system namespace. *

- * - * @param moduleCrit - * ModuleId - * @param matcher + * + * @param moduleCrit ModuleId + * @param matcher PatternMatcher * @return ModuleId[] */ public ModuleId[] listModules(ModuleId moduleCrit, PatternMatcher matcher) { @@ -214,10 +213,9 @@ public class SearchEngine { *

* ModuleRevisionId are returned in the system namespace. *

- * - * @param moduleCrit - * ModuleRevisionId - * @param matcher + * + * @param moduleCrit ModuleRevisionId + * @param matcher PatternMatcher * @return ModuleRevisionId[] */ public ModuleRevisionId[] listModules(ModuleRevisionId moduleCrit, PatternMatcher matcher) { @@ -269,7 +267,7 @@ public class SearchEngine { *

* ModuleRevisionId are returned in the system namespace. *

- * + * * @param resolver * the resolver in which modules should looked up * @param moduleCrit diff --git a/src/java/org/apache/ivy/core/settings/IvySettings.java b/src/java/org/apache/ivy/core/settings/IvySettings.java index 89c68efa..4b07c0bd 100644 --- a/src/java/org/apache/ivy/core/settings/IvySettings.java +++ b/src/java/org/apache/ivy/core/settings/IvySettings.java @@ -420,8 +420,8 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P * Default initialization of settings, useful when you don't want to load your settings from a * settings file or URL, but prefer to set them manually. By calling this method you will still * have the basic initialization done when loading settings. - * - * @throws IOException + * + * @throws IOException if something goes wrong */ public synchronized void defaultInit() throws IOException { if (getVariable("ivy.default.ivy.user.dir") != null) { @@ -491,7 +491,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Sets a deprecated variable with the value of the new variable - * + * * @param deprecatedKey * the deprecated variable name * @param newKey @@ -611,7 +611,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Substitute variables in the given string by their value found in the current set of variables - * + * * @param str * the string in which substitution should be made * @return the string where all current ivy variables have been substituted by their value If @@ -624,7 +624,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Substitute variables in the given map values by their value found in the current set of * variables - * + * * @param strings * the map of strings in which substitution should be made * @return a new map of strings in which all current ivy variables in values have been @@ -641,7 +641,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Returns the variables loaded in configuration file. Those variables may better be seen as ant * properties - * + * * @return IvyVariableContainer */ public synchronized IvyVariableContainer getVariables() { @@ -775,6 +775,13 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * regular expressions as explained in Pattern class may be used in attributes + * + * @param attributes Map + * @param matcher PatternMatcher + * @param resolverName String + * @param branch String + * @param conflictManager String + * @param resolveMode String */ public synchronized void addModuleConfiguration(Map attributes, PatternMatcher matcher, String resolverName, String branch, String conflictManager, @@ -789,12 +796,12 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P *

* If the specified file name is relative it is resolved with respect to the settings's base * directory. - * + * * @param fileName * The name of the file to resolve. Must not be null. - * + * * @return the resolved File. - * + * */ public synchronized File resolveFile(String fileName) { return FileUtil.resolveFile(baseDir, fileName); @@ -1211,7 +1218,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Filters the names list by removing all names that should be ignored as defined by the listing * ignore list - * + * * @param names ditto */ public synchronized void filterIgnore(Collection names) { @@ -1443,7 +1450,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Use a different variable container. - * + * * @param variables IvyVariableContainer */ public synchronized void setVariableContainer(IvyVariableContainer variables) { @@ -1490,7 +1497,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Validates the settings, throwing an {@link IllegalStateException} if the current state is not * valid. - * + * * @throws IllegalStateException * if the settings is not valid. */ @@ -1508,7 +1515,7 @@ public class IvySettings implements SortEngineSettings, PublishEngineSettings, P /** * Validates all {@link Validatable} objects in the collection. - * + * * @param values * the collection of objects to validate. * @throws IllegalStateException diff --git a/src/java/org/apache/ivy/core/sort/CollectionOfModulesToSort.java b/src/java/org/apache/ivy/core/sort/CollectionOfModulesToSort.java index 1f335b9b..93e228ba 100644 --- a/src/java/org/apache/ivy/core/sort/CollectionOfModulesToSort.java +++ b/src/java/org/apache/ivy/core/sort/CollectionOfModulesToSort.java @@ -32,8 +32,10 @@ import org.apache.ivy.plugins.version.VersionMatcher; /** * Wrap a collection of descriptors wrapped themselves in ModuleInSort elements. It contains some - * dedicated function to retrieve module descriptors based on dependencies descriptors.
+ * dedicated function to retrieve module descriptors based on dependencies descriptors. + *

* This class is designed to be used internally by the ModuleDescriptorSorter. + *

*/ class CollectionOfModulesToSort implements Iterable { @@ -86,7 +88,7 @@ class CollectionOfModulesToSort implements Iterable { /** * Find a matching module descriptor in the list of module to sort. - * + * * @param descriptor ditto * @return a ModuleDescriptor from the collection of module descriptors to sort. If none exists * returns null. diff --git a/src/java/org/apache/ivy/core/sort/ModuleDescriptorSorter.java b/src/java/org/apache/ivy/core/sort/ModuleDescriptorSorter.java index da0fb3b7..330f3020 100644 --- a/src/java/org/apache/ivy/core/sort/ModuleDescriptorSorter.java +++ b/src/java/org/apache/ivy/core/sort/ModuleDescriptorSorter.java @@ -29,10 +29,12 @@ import org.apache.ivy.plugins.version.VersionMatcher; import org.apache.ivy.util.Message; /** - * Inner helper class for sorting ModuleDescriptors.
+ * Inner helper class for sorting ModuleDescriptors. + *

* ModuleDescriptorSorter use CollectionOfModulesToSort to find the dependencies of the modules, and * use ModuleInSort to store some temporary values attached to the modules to sort. - * + *

+ * * @see ModuleInSort * @see CollectionOfModulesToSort */ @@ -54,9 +56,9 @@ public class ModuleDescriptorSorter { /** * Iterates over all modules calling sortModuleDescriptorsHelp. - * + * * @return sorted module - * @throws CircularDependencyException + * @throws CircularDependencyException somehow */ public List sortModuleDescriptors() throws CircularDependencyException { Message.debug("Nbr of module to sort : " + moduleDescriptors.size()); @@ -73,10 +75,10 @@ public class ModuleDescriptorSorter { * When a loop is detected by a recursive call, the moduleDescriptors are not added immediately * added to the sorted list. They are added as loop dependencies of the root, and will be added * to the sorted list only when the root itself will be added. - * + * * @param current * Current module to add to sorted list. - * @throws CircularDependencyException + * @throws CircularDependencyException somehow */ private void sortModuleDescriptorsHelp(ModuleInSort current, ModuleInSort caller) throws CircularDependencyException { diff --git a/src/java/org/apache/ivy/core/sort/ModuleInSort.java b/src/java/org/apache/ivy/core/sort/ModuleInSort.java index 225ee88c..686504e5 100644 --- a/src/java/org/apache/ivy/core/sort/ModuleInSort.java +++ b/src/java/org/apache/ivy/core/sort/ModuleInSort.java @@ -31,18 +31,21 @@ import org.apache.ivy.util.Message; /** * Decorates a ModuleDescriptor with some attributes used during the sort. Thus every instance of a - * ModuleInSort can be used in only one ModuleDescriptorSorter at a time.
- * The added fields are :
+ * ModuleInSort can be used in only one ModuleDescriptorSorter at a time. + *

+ * The added fields are: + *

*
    - *
  • isSorted : is true iff this module has already been added to the sorted list. - *
    • + *
  • isSorted : is true iff this module has already been added to the sorted + * list.
    • *
  • loopElements : When the module is the root of a loop (=the first element of a * loop met during the sort), loopElements contains all ModuleInSort of the loop * (excluding the root itself.
    • *
  • isLoopIntermediateElement : When a loop is detected, all modules included in the * loop (except the root) have isLoopIntermediateElement set to true.
    • *
  • caller : During the sort, we traverse recursively the graph. When doing that, - * caller point to the parent element. + * caller point to the parent element.
    • + *
*/ class ModuleInSort { @@ -103,7 +106,7 @@ class ModuleInSort { * dependency. If it is, all the elements of the loop are flagged as 'loopIntermediateElement', * and the loopElements of this module (which is the root of the loop) is updated. The * depStrategy is invoked on order to report a correct circular loop message. - * + * * @param futurCaller ModuleInSort * @param depStrategy CircularDependencyStrategy * @return true if a loop is detected. @@ -130,7 +133,7 @@ class ModuleInSort { * Add this module to the sorted list except if this module is an intermediary element of a * loop. If this module is the 'root' of a loop, then all elements of that loops are added * before. - * + * * @param sorted * The list of sorted elements on which this module will be added */ diff --git a/src/java/org/apache/ivy/osgi/core/BundleInfoAdapter.java b/src/java/org/apache/ivy/osgi/core/BundleInfoAdapter.java index c97d9665..2545de1e 100644 --- a/src/java/org/apache/ivy/osgi/core/BundleInfoAdapter.java +++ b/src/java/org/apache/ivy/osgi/core/BundleInfoAdapter.java @@ -77,11 +77,14 @@ public class BundleInfoAdapter { } /** - * + * @param parser ModuleDescriptorParser * @param baseUri * uri to help build the absolute url if the bundle info has a relative uri. + * @param bundle BundleInfo + * @param manifest Manifest + * @param profileProvider ExecutionEnvironmentProfileProvider * @return DefaultModuleDescriptor ditto - * @throws ProfileNotFoundException + * @throws ProfileNotFoundException if descriptor is not found */ public static DefaultModuleDescriptor toModuleDescriptor(ModuleDescriptorParser parser, URI baseUri, BundleInfo bundle, Manifest manifest, diff --git a/src/java/org/apache/ivy/osgi/util/DelegatingHandler.java b/src/java/org/apache/ivy/osgi/util/DelegatingHandler.java index bebdc1f9..16fb9677 100644 --- a/src/java/org/apache/ivy/osgi/util/DelegatingHandler.java +++ b/src/java/org/apache/ivy/osgi/util/DelegatingHandler.java @@ -107,7 +107,7 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con /** * Return an sort of identifier of the current element being parsed. It will only be used for * logging purpose. - * + * * @return an empty string by default */ protected String getCurrentElementIdentifier() { @@ -160,10 +160,11 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @throws SAXException API told me so */ protected void doStartDocument() throws SAXException { - // by default do nothing } @Override @@ -179,10 +180,11 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @throws SAXException API told me so */ protected void doEndDocument() throws SAXException { - // by default do nothing } @Override @@ -231,23 +233,27 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * Called when the expected node is achieved - * + * Called when the expected node is achieved; nothing to do by default. + * * @param atts * the xml attributes attached to the expected node * @exception SAXException * in case the parsing should be completely stopped */ protected void handleAttributes(Attributes atts) throws SAXException { - // nothing to do by default } /** - * @throws SAXException + * By default do nothing. + * + * @param uri String + * @param localName String + * @param name String + * @param atts Attributes + * @throws SAXException API told me so */ protected void doStartElement(String uri, String localName, String name, Attributes atts) throws SAXException { - // by default do nothing } @Override @@ -284,10 +290,14 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param uri String + * @param localName String + * @param name String + * @throws SAXException API told me so */ protected void doEndElement(String uri, String localName, String name) throws SAXException { - // by default do nothing } public static abstract class ChildElementHandler { @@ -315,7 +325,10 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * @param ch char[] + * @param start int + * @param length int + * @throws SAXException if something goes wrong */ protected void doCharacters(char[] ch, int start, int length) throws SAXException { if (bufferingChar) { @@ -336,10 +349,13 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param prefix String + * @param uri String + * @throws SAXException API told me so */ protected void doStartPrefixMapping(String prefix, String uri) throws SAXException { - // by default do nothing } @Override @@ -355,10 +371,12 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param prefix String + * @throws SAXException API told me so */ protected void doEndPrefixMapping(String prefix) throws SAXException { - // by default do nothing } @Override @@ -374,10 +392,14 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing + * + * @param ch char[] + * @param start int + * @param length int + * @throws SAXException API told me so */ protected void doIgnorableWhitespace(char[] ch, int start, int length) throws SAXException { - // by default do nothing } @Override @@ -394,11 +416,15 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param name String + * @param publicId String + * @param systemId String + * @throws SAXException API told me so */ protected void doNotationDecl(String name, String publicId, String systemId) throws SAXException { - // by default do nothing } @Override @@ -414,10 +440,13 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing + * + * @param target String + * @param data String + * @throws SAXException API told me so */ protected void doProcessingInstruction(String target, String data) throws SAXException { - // by default do nothing } @Override @@ -433,10 +462,12 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param name String + * @throws SAXException API told me so */ protected void doSkippedEntity(String name) throws SAXException { - // by default do nothing } @Override @@ -453,11 +484,16 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param name String + * @param publicId String + * @param systemId String + * @param notationName String + * @throws SAXException API told me so */ protected void doUnparsedEntityDecl(String name, String publicId, String systemId, String notationName) throws SAXException { - // by default do nothing } // ERROR HANDLING @@ -475,10 +511,12 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param exception SAXParseException + * @throws SAXException API told me so */ protected void doWarning(SAXParseException exception) throws SAXException { - // by default do nothing } @Override @@ -494,10 +532,12 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param exception SAXParseException + * @throws SAXException API told me so */ protected void doError(SAXParseException exception) throws SAXException { - // by default do nothing } @Override @@ -513,10 +553,12 @@ public class DelegatingHandler extends DefaultHandler implements DTDHandler, Con } /** - * @throws SAXException + * By default do nothing. + * + * @param exception SAXParseException + * @throws SAXException API told me so */ protected void doFatalError(SAXParseException exception) throws SAXException { - // by default do nothing } // ////////////////////// diff --git a/src/java/org/apache/ivy/plugins/circular/CircularDependencyHelper.java b/src/java/org/apache/ivy/plugins/circular/CircularDependencyHelper.java index 69dbdba5..123dd965 100644 --- a/src/java/org/apache/ivy/plugins/circular/CircularDependencyHelper.java +++ b/src/java/org/apache/ivy/plugins/circular/CircularDependencyHelper.java @@ -34,7 +34,7 @@ public final class CircularDependencyHelper { /** * Returns a string representation of this circular dependency graph - * + * * @param mrids * in order of circular dependency * @return a string representation of this circular dependency graph @@ -62,7 +62,8 @@ public final class CircularDependencyHelper { /** * @param loopElements - * a List + * a List<ModuleDescriptor> + * @return String */ public static String formatMessageFromDescriptors(List loopElements) { ModuleRevisionId[] mrids = new ModuleRevisionId[loopElements.size()]; diff --git a/src/java/org/apache/ivy/plugins/conflict/LatestCompatibleConflictManager.java b/src/java/org/apache/ivy/plugins/conflict/LatestCompatibleConflictManager.java index 4501e723..e7b0ff63 100644 --- a/src/java/org/apache/ivy/plugins/conflict/LatestCompatibleConflictManager.java +++ b/src/java/org/apache/ivy/plugins/conflict/LatestCompatibleConflictManager.java @@ -46,17 +46,17 @@ import org.apache.ivy.util.Message; * set of compatible dependencies, even if it requires stepping back to older revisions (as long as * they are in the set of compatibility). *

- * Here is an example of what this conflict manager is able to do:
+ * Here is an example of what this conflict manager is able to do: + *

* Available Modules: - * * 
  * #A;2->{ #B;[1.0,1.5] #C;[2.0,2.5] }
  * #B;1.4->#D;1.5
  * #B;1.5->#D;2.0
  * #C;2.5->#D;[1.0,1.6]
  *
- * - * Result: #B;1.4, #C;2.5, #D;1.5
+ * Result: #B;1.4, #C;2.5, #D;1.5 + *

* DetailsThe conflict manager finds that the latest matching version of #B (1.5) depends on * a version of #D incompatible with what is expected by the latest matching version of #C. Hence * the conflict manager blacklists #B;1.5, and the version range [1.0,1.5] is resolved again to end @@ -126,7 +126,7 @@ public class LatestCompatibleConflictManager extends LatestConflictManager { * Handles an incompatible conflict *

* An incompatible conflicts is handled with this pseudo algorithm: - * + * * 

      * take latest among two nodes in conflict
      *   for all callers
@@ -139,9 +139,9 @@ public class LatestCompatibleConflictManager extends LatestConflictManager {
      *   else
      *     throw strict conflict exception
      *
- * + * *

- * + * * @param parent * the parent node of nodes in conflict * @param conflicts @@ -238,7 +238,7 @@ public class LatestCompatibleConflictManager extends LatestConflictManager { /** * Tries to blacklist exactly one version for all callers paths. - * + * * @param versionMatcher * the version matcher to use to interpret versions * @param conflictParent diff --git a/src/java/org/apache/ivy/plugins/latest/WorkspaceLatestStrategy.java b/src/java/org/apache/ivy/plugins/latest/WorkspaceLatestStrategy.java index 64ef7ec7..97ab1925 100644 --- a/src/java/org/apache/ivy/plugins/latest/WorkspaceLatestStrategy.java +++ b/src/java/org/apache/ivy/plugins/latest/WorkspaceLatestStrategy.java @@ -22,8 +22,8 @@ import java.util.List; /** * A strategy which delegate to another strategy, unless for the latest and working revisions which - * are considered as superior to any other revision. < br/> - * NB : it is for internal usage of Ivy only! + * are considered as superior to any other revision. + *

NB : it is for internal usage of Ivy only!

*/ public class WorkspaceLatestStrategy extends AbstractLatestStrategy { diff --git a/src/java/org/apache/ivy/plugins/lock/FileBasedLockStrategy.java b/src/java/org/apache/ivy/plugins/lock/FileBasedLockStrategy.java index 8fa26434..142898cb 100644 --- a/src/java/org/apache/ivy/plugins/lock/FileBasedLockStrategy.java +++ b/src/java/org/apache/ivy/plugins/lock/FileBasedLockStrategy.java @@ -139,12 +139,12 @@ public abstract class FileBasedLockStrategy extends AbstractLockStrategy { /** * Determine the state of the lockfile. - * + * * Must be called from within a synchronized block. - * + * * Three possibilities exist: - The lock is held by the current thread (>0) - The lock is held * by one or more different threads (-1) - The lock is not held at all (0). - * + * * @param file * file to lock * @param forThread @@ -169,10 +169,10 @@ public abstract class FileBasedLockStrategy extends AbstractLockStrategy { /** * Record that this thread holds the lock. - * + * * Asserts that the lock has been previously grabbed by this thread. Must be called from a * synchronized block in which the lock was grabbed. - * + * * @param file * file which has been locked * @param forThread @@ -193,11 +193,11 @@ public abstract class FileBasedLockStrategy extends AbstractLockStrategy { /** * Decrease depth of this thread's lock. - * + * * Must be called within a synchronized block. - * + * * If this returns 0, the caller is responsible for releasing the lock within that same block. - * + * * @param file * file for which lock depth is being decreased * @param forThread @@ -225,6 +225,9 @@ public abstract class FileBasedLockStrategy extends AbstractLockStrategy { /** * Return a string naming the threads which currently hold this lock. + * + * @param file File + * @return String */ protected String getCurrentLockHolderNames(File file) { StringBuilder sb = new StringBuilder(); diff --git a/src/java/org/apache/ivy/plugins/lock/LockStrategy.java b/src/java/org/apache/ivy/plugins/lock/LockStrategy.java index a28d6f87..31a0fb80 100644 --- a/src/java/org/apache/ivy/plugins/lock/LockStrategy.java +++ b/src/java/org/apache/ivy/plugins/lock/LockStrategy.java @@ -28,10 +28,11 @@ import org.apache.ivy.core.module.descriptor.Artifact; * Note that some implementations may actually choose to NOT perform locking, when no lock is * necessary (cache not shared). Some other implementations may choose to lock the cache for the * download of a whole module (not possible yet), or at the artifact level. - *

*

+ *

* The lock methods should return true when the lock is either actually acquired or not performed by - * the strategy.

+ * the strategy. + *

*

* Locking used in the locking strategy must support reentrant lock. Reentrant locking should be * performed for the whole strategy. @@ -41,14 +42,14 @@ public interface LockStrategy { /** * Returns the name of the strategy - * + * * @return the name of the strategy */ String getName(); /** * Performs a lock before downloading the given {@link Artifact} to the given file. - * + * * @param artifact * the artifact about to be downloaded * @param artifactFileToDownload @@ -62,7 +63,7 @@ public interface LockStrategy { /** * Release the lock acquired for an artifact download. - * + * * @param artifact * the artifact for which the lock was acquired * @param artifactFileToDownload diff --git a/src/java/org/apache/ivy/plugins/matcher/ExactOrRegexpPatternMatcher.java b/src/java/org/apache/ivy/plugins/matcher/ExactOrRegexpPatternMatcher.java index 68e2f745..0e45c147 100644 --- a/src/java/org/apache/ivy/plugins/matcher/ExactOrRegexpPatternMatcher.java +++ b/src/java/org/apache/ivy/plugins/matcher/ExactOrRegexpPatternMatcher.java @@ -20,11 +20,12 @@ package org.apache.ivy.plugins.matcher; /** * A pattern matcher that tries to match exactly the input with the expression, or match it as a * pattern. - *

+ *

* The evaluation for matching is perform first by checking if expression and input are equals (via * equals method) else it attempts to do it by trying to match the input using the expression as a * regexp. - * + *

+ * * @see ExactPatternMatcher * @see RegexpPatternMatcher */ diff --git a/src/java/org/apache/ivy/plugins/matcher/ExactPatternMatcher.java b/src/java/org/apache/ivy/plugins/matcher/ExactPatternMatcher.java index 0613e380..c29eff7d 100644 --- a/src/java/org/apache/ivy/plugins/matcher/ExactPatternMatcher.java +++ b/src/java/org/apache/ivy/plugins/matcher/ExactPatternMatcher.java @@ -19,9 +19,10 @@ package org.apache.ivy.plugins.matcher; /** * Implementation of an exact matcher. - *

+ *

* The matching will be performed against an expression being a string. It will only matches if both * strings are equal (per equals()) rule or if both strings are null. + *

*/ public/* @Immutable */final class ExactPatternMatcher extends AbstractPatternMatcher { diff --git a/src/java/org/apache/ivy/plugins/matcher/GlobPatternMatcher.java b/src/java/org/apache/ivy/plugins/matcher/GlobPatternMatcher.java index 96a8d3ae..9e9b22a1 100644 --- a/src/java/org/apache/ivy/plugins/matcher/GlobPatternMatcher.java +++ b/src/java/org/apache/ivy/plugins/matcher/GlobPatternMatcher.java @@ -30,10 +30,12 @@ import org.apache.oro.text.regex.Perl5Matcher; *
  • * - Matches zero or more characters
    • *
  • ? - Matches exactly one character.
    • * - *

    - * Note that this matcher is available only with in your classpath. - * + *

    + * NOTE: this matcher is available only with + * Apache Jakarta Oro 2.0.8 + * in your classpath. + *

    + * * @see GlobCompiler */ public/* @Immutable */final class GlobPatternMatcher extends AbstractPatternMatcher { diff --git a/src/java/org/apache/ivy/plugins/matcher/PatternMatcher.java b/src/java/org/apache/ivy/plugins/matcher/PatternMatcher.java index 27b35ebd..16b5145c 100644 --- a/src/java/org/apache/ivy/plugins/matcher/PatternMatcher.java +++ b/src/java/org/apache/ivy/plugins/matcher/PatternMatcher.java @@ -19,9 +19,10 @@ package org.apache.ivy.plugins.matcher; /** * Interface for a pattern matcher. - *

    + *

    * The pattern matcher is the main abstraction regarding the matching of an expression. * Implementation may vary depending on the expression syntax handling that is desired. + *

    */ public interface PatternMatcher { @@ -52,7 +53,7 @@ public interface PatternMatcher { /** * Return the matcher for the given expression. - * + * * @param expression * the expression to be matched. Cannot be null ? * @return the matcher instance for the given expression. Never null. @@ -61,7 +62,7 @@ public interface PatternMatcher { /** * return the name of this pattern matcher - * + * * @return the name of this pattern matcher. Never null. * @see #EXACT * @see #REGEXP diff --git a/src/java/org/apache/ivy/plugins/parser/ModuleDescriptorParser.java b/src/java/org/apache/ivy/plugins/parser/ModuleDescriptorParser.java index 0971f338..cfd36366 100644 --- a/src/java/org/apache/ivy/plugins/parser/ModuleDescriptorParser.java +++ b/src/java/org/apache/ivy/plugins/parser/ModuleDescriptorParser.java @@ -39,8 +39,12 @@ public interface ModuleDescriptorParser { * Convert a module descriptor to an ivy file. This method MUST close the given input stream * when job is finished * - * @param is - * input stream with opened on original module descriptor resource + * @param is input stream with opened on original module descriptor resource + * @param res Resource + * @param destFile File + * @param md ModuleDescriptor + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public void toIvyFile(InputStream is, Resource res, File destFile, ModuleDescriptor md) throws ParseException, IOException; diff --git a/src/java/org/apache/ivy/plugins/parser/ParserSettings.java b/src/java/org/apache/ivy/plugins/parser/ParserSettings.java index 662736c7..82945471 100644 --- a/src/java/org/apache/ivy/plugins/parser/ParserSettings.java +++ b/src/java/org/apache/ivy/plugins/parser/ParserSettings.java @@ -55,7 +55,7 @@ public interface ParserSettings { String getDefaultBranch(ModuleId moduleId); /** - * Returns the namespace context in which the current descriptor is parsed. + * @return the namespace context in which the current descriptor is parsed. */ Namespace getContextNamespace(); diff --git a/src/java/org/apache/ivy/plugins/parser/m2/PomModuleDescriptorParser.java b/src/java/org/apache/ivy/plugins/parser/m2/PomModuleDescriptorParser.java index 9bb6433e..ced6e55a 100644 --- a/src/java/org/apache/ivy/plugins/parser/m2/PomModuleDescriptorParser.java +++ b/src/java/org/apache/ivy/plugins/parser/m2/PomModuleDescriptorParser.java @@ -59,11 +59,13 @@ import org.xml.sax.SAXException; /** * A parser for Maven 2 POM. *

    - * The configurations used in the generated module descriptor mimics the behavior defined by maven 2 - * scopes, as documented here:
    - * http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html The - * PomModuleDescriptorParser use a PomDomReader to read the pom, and the PomModuleDescriptorBuilder - * to write the ivy module descriptor using the info read by the PomDomReader. + * The configurations used in the generated module descriptor mimics the behavior defined by Maven 2 + * scopes, as documented + * here. + * The PomModuleDescriptorParser use a PomDomReader to read the pom, and the + * PomModuleDescriptorBuilder to write the ivy module descriptor using the info read by the + * PomDomReader. + *

    */ public final class PomModuleDescriptorParser implements ModuleDescriptorParser { diff --git a/src/java/org/apache/ivy/plugins/parser/m2/PomReader.java b/src/java/org/apache/ivy/plugins/parser/m2/PomReader.java index b9e82013..93d128b3 100644 --- a/src/java/org/apache/ivy/plugins/parser/m2/PomReader.java +++ b/src/java/org/apache/ivy/plugins/parser/m2/PomReader.java @@ -156,6 +156,9 @@ public class PomReader { * Add a property if not yet set and value is not null. This guarantees * that property keeps the first value that is put on it and that the * properties are never null. + * + * @param prop String + * @param val String */ public void setProperty(String prop, String val) { if (!properties.containsKey(prop) && val != null) { diff --git a/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorParser.java b/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorParser.java index a272d65d..0dcdb8a3 100644 --- a/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorParser.java +++ b/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorParser.java @@ -107,8 +107,8 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { * the real resource to parse, used for log only * @param validate boolean * @return ModuleDescriptor - * @throws ParseException - * @throws IOException + * @throws ParseException if something goes wrong + * @throws IOException if something goes wrong */ public ModuleDescriptor parseDescriptor(ParserSettings ivySettings, URL xmlURL, Resource res, boolean validate) throws ParseException, IOException { @@ -136,7 +136,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { *

    * Override this method if you want to use a custom Parser. *

    - * + * * @param ivySettings * the settings to use during parsing * @return the Parser instance used for parsing Ivy files @@ -396,7 +396,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Default parent location to check (for dev ONLY) - * + * * @return a relative path to a parent module descriptor */ protected String getDefaultParentLocation() { @@ -411,9 +411,9 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { *
  • cache to find a resolved parent descriptor
    • *
  • ask repositories to retrieve the parent module descriptor
    • * - * + * * @param attributes Attributes - * @throws ParseException + * @throws ParseException if something goes wrong */ protected void extendsStarted(Attributes attributes) throws ParseException { String parentOrganisation = settings.substitute(attributes.getValue("organisation")); @@ -482,7 +482,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Merge current module with a given module descriptor and specify what should be inherited * through extendTypes argument - * + * * @param extendTypes * specify what should be inherited * @param parent @@ -521,7 +521,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Merge everything from a given parent - * + * * @param parent * a given parent module descriptor */ @@ -536,7 +536,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Explain how to inherit metadata related to info element - * + * * @param parent * a given parent module descriptor */ @@ -589,7 +589,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describes how to merge configurations elements - * + * * @param parent * the module descriptor */ @@ -612,7 +612,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describes how dependencies should be inherited - * + * * @param dependencies * array of dependencies to inherit */ @@ -628,7 +628,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describes how to merge description - * + * * @param description * description going to be inherited */ @@ -641,7 +641,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describes how to merge licenses - * + * * @param licenses * licenses going to be inherited */ @@ -653,7 +653,7 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describes how to merge exclude rules - * + * * @param excludeRules * exclude rules going to be inherited */ @@ -665,11 +665,11 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Returns the parent module using the location attribute (for dev purpose). - * + * * @param location * a given location - * @throws IOException - * @throws ParseException + * @throws IOException if something goes wrong + * @throws ParseException if something goes wrong */ private ModuleDescriptor parseParentModuleOnFilesystem(String location) throws IOException, ParseException { @@ -702,12 +702,12 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { /** * Describe how to parse a {@link ModuleDescriptor} by asking repositories - * + * * @param parentMrid * a given {@link ModuleRevisionId} to find * @return a {@link ModuleDescriptor} if found. Return null if no {@link ModuleDescriptor} * was found - * @throws ParseException + * @throws ParseException if something goes wrong */ protected ModuleDescriptor parseOtherIvyFile(ModuleRevisionId parentMrid) throws ParseException { @@ -911,11 +911,12 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { String branch = settings.substitute(attributes.getValue("branch")); String branchConstraint = settings.substitute(attributes.getValue("branchConstraint")); - // if (branchConstraint == null) { - // // there was no branch constraint before, so we should - // // set the branchConstraint to the current default branch - // branchConstraint = settings.getDefaultBranch(ModuleId.newInstance(org, name)); - // } + /* if (branchConstraint == null) { + * // there was no branch constraint before, so we should + * // set the branchConstraint to the current default branch + * branchConstraint = settings.getDefaultBranch(ModuleId.newInstance(org, name)); + * } + */ String rev = settings.substitute(attributes.getValue("rev")); String revConstraint = settings.substitute(attributes.getValue("revConstraint")); @@ -1167,15 +1168,12 @@ public class XmlModuleDescriptorParser extends AbstractModuleDescriptorParser { protected void addConfiguration(String c) { confAware.addConfiguration(c); if (state == State.EXCLUDE) { - // we are adding a configuration to a module wide exclude rule - // we have nothing special to do here, the rule has already been added to the module - // descriptor + // we are adding a configuration to a module wide exclude rule we have nothing + // special to do here, the rule has already been added to the module descriptor } else { // we are currently adding a configuration to either an include, exclude or artifact - // element - // of a dependency. This means that we have to add this element to the corresponding - // conf - // of the current dependency descriptor + // element of a dependency. This means that we have to add this element to the + // corresponding conf of the current dependency descriptor if (confAware instanceof DependencyArtifactDescriptor) { dd.addDependencyArtifact(c, (DependencyArtifactDescriptor) confAware); } else if (confAware instanceof IncludeRule) { diff --git a/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorUpdater.java b/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorUpdater.java index b373acff..b1aafa93 100644 --- a/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorUpdater.java +++ b/src/java/org/apache/ivy/plugins/parser/xml/XmlModuleDescriptorUpdater.java @@ -84,11 +84,15 @@ public final class XmlModuleDescriptorUpdater { /** * used to copy a module descriptor xml file (also known as ivy file) and update the revisions * of its dependencies, its status and revision - * + * * @param srcURL * the url of the source module descriptor file * @param destFile * The file to which the updated module descriptor should be output + * @param options + * UpdateOptions + * @throws IOException if something goes wrong + * @throws SAXException if something goes wrong */ public static void update(URL srcURL, File destFile, UpdateOptions options) throws IOException, SAXException { @@ -932,7 +936,7 @@ public final class XmlModuleDescriptorUpdater { /** * Write XML elements that do not appear in the source descriptor, but have been copied in * from a parent module descriptor via <extends> declaration. - * + * * @param merged * child descriptor containing the merged data * @param items @@ -1003,7 +1007,7 @@ public final class XmlModuleDescriptorUpdater { * Collect the given list of inherited descriptor items into lists keyed by parent Id. Thus * all of the items inherited from parent A can be written together, then all of the items * from parent B, and so on. - * + * * @param merged * the merged child descriptor * @param items @@ -1077,13 +1081,13 @@ public final class XmlModuleDescriptorUpdater { * elements like "configurations" and "dependencies" appear in the parent descriptor, but * are completely missing in the child descriptor. *

    - * + * *

    * For example, if "moduleElement" is "dependencies", guarantees that "configurations" has * been written. If moduleElement is null, then all missing merged * elements will be flushed. *

    - * + * * @param moduleElement * a descriptor element name, for example "configurations" or "info" */ @@ -1312,12 +1316,13 @@ public final class XmlModuleDescriptorUpdater { protected static interface ItemPrinter { /** * Print an XML representation of item to out. - * + * * @param parent * the module descriptor containing item * @param item * subcomponent of the descriptor, for example a {@link DependencyDescriptor} or * {@link Configuration} + * @param out PrintWriter */ public void print(ModuleDescriptor parent, Object item, PrintWriter out); } diff --git a/src/java/org/apache/ivy/plugins/report/XmlReportParser.java b/src/java/org/apache/ivy/plugins/report/XmlReportParser.java index c24fc11c..a0d57370 100644 --- a/src/java/org/apache/ivy/plugins/report/XmlReportParser.java +++ b/src/java/org/apache/ivy/plugins/report/XmlReportParser.java @@ -322,6 +322,8 @@ public class XmlReportParser { /** * Returns the ModuleRevisionId of the resolved module. + * + * @return ModuleRevisionId */ public ModuleRevisionId getResolvedModule() { return parser.getResolvedModule(); diff --git a/src/java/org/apache/ivy/plugins/repository/Repository.java b/src/java/org/apache/ivy/plugins/repository/Repository.java index 5bec7656..e78f20a1 100644 --- a/src/java/org/apache/ivy/plugins/repository/Repository.java +++ b/src/java/org/apache/ivy/plugins/repository/Repository.java @@ -26,28 +26,19 @@ import org.apache.ivy.core.module.descriptor.Artifact; /** * Represents a collection of resources available to Ivy. Ivy uses one or more repositories as both * a source of resources for Ivy enabled build systems and as a distribution center for resources - * generated by Ivy enabled build systems.

    - *

    - * A repository supports the following fundamental operations + * generated by Ivy enabled build systems. + *

    A repository supports the following fundamental operations

    *
      *
    • retrieving a resource from the repository.
      • *
    • transferring a resource to the repository.
      • *
    • retrieving a listing of resources.
      • *
    - *

    - *

    Resource Retrieval

    - *

    - * {@link #get} retrieves a resource specified by a provided identifier creating a new file . - *

    - *

    resource Publication

    - *

    - * {@link #put} transfers a file to the repository. - *

    - *

    resource Listing

    - *

    - * {@link #list} returns a listing of file like objects belonging to a specified parent directory. - *

    - *

    + *

    Resource Retrieval

    + *

    {@link #get} retrieves a resource specified by a provided identifier creating a new file.

    + *

    Resource Publication

    + *

    {@link #put} transfers a file to the repository.

    + *

    resource Listing

    + *

    {@link #list} returns a listing of file like objects belonging to a specified parent directory.

    */ public interface Repository { @@ -55,7 +46,7 @@ public interface Repository { * Return the resource associated with a specified identifier. If the resource does not exist, * it should return a Resource with exists() returning false. An IOException should only be * thrown when a real IO problem occurs, like the impossibility to connect to a server. - * + * * @param source * A string identifying the resource. * @return The resource associated with the resource identifier. @@ -66,7 +57,7 @@ public interface Repository { /** * Fetch a resource from the repository. - * + * * @param source * A string identifying the resource to be fetched. * @param destination @@ -78,7 +69,7 @@ public interface Repository { /** * Transfer a resource to the repository - * + * * @param artifact * The artifact to be transferred. * @param source @@ -95,7 +86,7 @@ public interface Repository { /** * Return a listing of resources names - * + * * @param parent * The parent directory from which to generate the listing. * @return A listing of the parent directory's file content @@ -106,7 +97,7 @@ public interface Repository { /** * Add a listener to the repository. - * + * * @param listener * The listener to attach to the repository. */ @@ -114,7 +105,7 @@ public interface Repository { /** * Remove a listener on the repository - * + * * @param listener * The listener to remove */ @@ -122,7 +113,7 @@ public interface Repository { /** * Determine if a given listener is attached to the repository. - * + * * @param listener * The listener being queried * @return true if the provided listener is attached to the repository, @@ -132,14 +123,14 @@ public interface Repository { /** * Get the repository's file separator string. - * + * * @return The repository's file separator delimiter */ String getFileSeparator(); /** * Normalize a string. - * + * * @param source * The string to normalize. * @return The normalized string. @@ -148,6 +139,8 @@ public interface Repository { /** * Return the name of the repository + * + * @return String name */ String getName(); } diff --git a/src/java/org/apache/ivy/plugins/repository/Resource.java b/src/java/org/apache/ivy/plugins/repository/Resource.java index 7a622693..950c02a4 100644 --- a/src/java/org/apache/ivy/plugins/repository/Resource.java +++ b/src/java/org/apache/ivy/plugins/repository/Resource.java @@ -29,18 +29,17 @@ import java.io.InputStream; *
  • size of the resource in bytes.
    • *
  • if the resource is available.
    • * - *

    Implementation Notes

    In implementing the interface you need to ensure the following - * behaviors: + *

    Implementation Notes

    + * In implementing the interface you need to ensure the following behaviors: *
      - *
    • All of the methods specified in the interface fail by returning an empty value ( - * false, 0, ""). In other words, the specified interface + *
    • All of the methods specified in the interface fail by returning an empty value + * (false, 0, ""). In other words, the specified interface * methods should not throw RuntimeExceptions.
      • *
    • Failure conditions should be logged using the {@link org.apache.ivy.util.Message#verbose} * method.
      • *
    • Failure of one of the interface's specified methods results in all other interface specified * methods returning an empty value (false, 0, "").
      • *
    - *

    */ public interface Resource { @@ -68,7 +67,7 @@ public interface Resource { public long getContentLength(); /** - * Determine if the resource is available.

    Note that this method only checks for + * Determine if the resource is available. Note that this method only checks for * availability, not for actual existence. * * @return boolean value indicating if the resource is available. @@ -95,6 +94,7 @@ public interface Resource { * Opens a stream on this resource * * @return the opened input stream + * @throws IOException if something goes wrong */ public InputStream openStream() throws IOException; } diff --git a/src/java/org/apache/ivy/plugins/repository/TransferEvent.java b/src/java/org/apache/ivy/plugins/repository/TransferEvent.java index 68c5adf9..64517e7f 100644 --- a/src/java/org/apache/ivy/plugins/repository/TransferEvent.java +++ b/src/java/org/apache/ivy/plugins/repository/TransferEvent.java @@ -25,25 +25,25 @@ import org.apache.ivy.core.event.IvyEvent; * TransferEvent is used to notify TransferListeners about progress in transfer of resources form/to * the repository This class is LARGELY inspired by org.apache.maven.wagon.events.TransferEvent * released under the following copyright license: - * + * * 
    - * 
+ *
  *  Copyright 2001-2005 The Apache Software Foundation.
- * 
+ *
  *  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.
- * 
+ *
  *
    - * + * * Original class written by Michal Maczka. */ public class TransferEvent extends IvyEvent { @@ -184,9 +184,9 @@ public class TransferEvent extends IvyEvent { /** * Returns the request type. - * + * * @return Returns the request type. The Request type is one of - * TransferEvent.REQUEST_GET or TransferEvent.REQUEST_PUT + * TransferEvent.REQUEST_GET or TransferEvent.REQUEST_PUT */ public int getRequestType() { return requestType; @@ -194,10 +194,10 @@ public class TransferEvent extends IvyEvent { /** * Sets the request type - * + * * @param requestType * The requestType to set. The Request type value should be either - * TransferEvent.REQUEST_GET or TransferEvent.REQUEST_PUT. + * TransferEvent.REQUEST_GET or TransferEvent.REQUEST_PUT * @throws IllegalArgumentException * when */ @@ -303,22 +303,16 @@ public class TransferEvent extends IvyEvent { /** * Returns the elapsed time (in ms) between when the event entered one type until it entered * another event time. - *

    - * This is especially useful to get the elapsed transfer time: - * + *

    This is especially useful to get the elapsed transfer time:

    * 
          * getElapsedTime(TransferEvent.TRANSFER_STARTED, TransferEvent.TRANSFER_COMPLETED);
      *
    - * - *

    - *

    - * Special cases: + *

    Special cases:

    *
      *
    • returns -1 if the event never entered the fromEventType or the toEventType.
      • *
    • returns 0 if the event entered toEventType before fromEventType
      • *
    - *

    - * + * * @param fromEventType * the event type constant from which time should be measured * @param toEventType @@ -345,7 +339,7 @@ public class TransferEvent extends IvyEvent { /** * Checks the given event type is a valid event type, throws an {@link IllegalArgumentException} * if it isn't - * + * * @param eventType * the event type to check */ diff --git a/src/java/org/apache/ivy/plugins/repository/ssh/AbstractSshBasedRepository.java b/src/java/org/apache/ivy/plugins/repository/ssh/AbstractSshBasedRepository.java index 276cc253..d61c0ba3 100644 --- a/src/java/org/apache/ivy/plugins/repository/ssh/AbstractSshBasedRepository.java +++ b/src/java/org/apache/ivy/plugins/repository/ssh/AbstractSshBasedRepository.java @@ -68,10 +68,11 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * get a new session using the default attributes if the given String is a full uri, use the * data from the uri instead - * + * * @param pathOrUri * might be just a path or a full ssh or sftp uri * @return matching Session + * @throws IOException if something goes wrong */ protected Session getSession(String pathOrUri) throws IOException { URI uri = parseURI(pathOrUri); @@ -134,7 +135,7 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * Just check the uri for sanity - * + * * @param source * String of the uri * @return URI object of the String or null @@ -170,7 +171,7 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * Called, when user was not found in URL. Maintain static hash of credentials and retrieve or * ask credentials for host. - * + * * @param host * host for which we want to get credentials. * @return credentials for given host @@ -194,7 +195,7 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * closes the session and remove it from the cache (eg. on case of errors) - * + * * @param session * key for the cache * @param pathOrUri @@ -207,7 +208,7 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * set the default user to use for the connection if no user is given or a PEM file is used - * + * * @param user * to use */ @@ -224,7 +225,7 @@ public abstract class AbstractSshBasedRepository extends AbstractRepository { /** * Sets the full file path to use for accessing a PEM key file - * + * * @param filePath * fully qualified name */ diff --git a/src/java/org/apache/ivy/plugins/repository/ssh/SshCache.java b/src/java/org/apache/ivy/plugins/repository/ssh/SshCache.java index de876551..7b24ecb2 100644 --- a/src/java/org/apache/ivy/plugins/repository/ssh/SshCache.java +++ b/src/java/org/apache/ivy/plugins/repository/ssh/SshCache.java @@ -108,7 +108,7 @@ public final class SshCache { /** * attach an sftp channel to this cache entry - * + * * @param newChannel * to attach */ @@ -150,7 +150,7 @@ public final class SshCache { /** * key is username / host / port - * + * * @see #createCacheKey(String, String, int) for details */ private Map uriCacheMap = new HashMap(); @@ -177,7 +177,7 @@ public final class SshCache { /** * Creates a combined cache key from the given key parts - * + * * @param user * name of the user * @param host @@ -197,7 +197,7 @@ public final class SshCache { /** * retrieves a session entry for a given session from the cache - * + * * @param session * to retrieve cache entry for * @return null or the existing entry @@ -209,7 +209,7 @@ public final class SshCache { /** * Sets a session to a given combined key into the cache If an old session object already * exists, close and remove it - * + * * @param user * of the session * @param host @@ -246,7 +246,7 @@ public final class SshCache { /** * discards session entries from the cache - * + * * @param session * to clear */ @@ -259,10 +259,11 @@ public final class SshCache { /** * retrieves an sftp channel from the cache - * + * * @param session * to connect to * @return channelSftp or null if not successful (channel not existent or dead) + * @throws IOException if something goes wrong */ public ChannelSftp getChannelSftp(Session session) throws IOException { ChannelSftp channel = null; @@ -279,7 +280,7 @@ public final class SshCache { /** * attaches a channelSftp to an existing session cache entry - * + * * @param session * to attach the channel to * @param channel @@ -295,7 +296,7 @@ public final class SshCache { /** * Attempts to connect to a local SSH agent (using either UNIX sockets or PuTTY's Pageant) - * + * * @param jsch * Connection to be attached to an available local agent * @return true if connected to agent, false otherwise @@ -313,7 +314,7 @@ public final class SshCache { /** * Gets a session from the cache or establishes a new session if necessary - * + * * @param host * to connect to * @param port @@ -331,6 +332,7 @@ public final class SshCache { * @param allowedAgentUse * Whether to communicate with an agent for authentication * @return session or null if not successful + * @throws IOException if something goes wrong */ public Session getSession(String host, int port, String username, String userPassword, File pemFile, String pemPassword, File passFile, boolean allowedAgentUse) diff --git a/src/java/org/apache/ivy/plugins/repository/ssh/SshRepository.java b/src/java/org/apache/ivy/plugins/repository/ssh/SshRepository.java index cbe654f9..4590a67a 100644 --- a/src/java/org/apache/ivy/plugins/repository/ssh/SshRepository.java +++ b/src/java/org/apache/ivy/plugins/repository/ssh/SshRepository.java @@ -68,7 +68,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * Fetch the needed file information for a given file (size, last modification time) and report * it back in a SshResource - * + * * @param source * ssh uri for the file to get info for * @return SshResource filled with the needed information @@ -103,7 +103,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * Reads out the output of a ssh session exec - * + * * @param channel * Channel to read from * @param strStdout @@ -157,7 +157,7 @@ public class SshRepository extends AbstractSshBasedRepository { /* * (non-Javadoc) - * + * * @see org.apache.ivy.repository.Repository#list(java.lang.String) */ public List list(String parent) throws IOException { @@ -211,7 +211,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * Replace the argument placeholder with argument or append the argument if no placeholder is * present - * + * * @param command * with argument placeholder or not * @param argument ditto @@ -229,7 +229,7 @@ public class SshRepository extends AbstractSshBasedRepository { /* * (non-Javadoc) - * + * * @see org.apache.ivy.repository.Repository#put(java.io.File, java.lang.String, boolean) */ public void put(File source, String destination, boolean overwrite) throws IOException { @@ -279,7 +279,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * Tries to create a directory path on the target system - * + * * @param path * to create * @param session @@ -316,7 +316,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * check for existence of file or dir on target system - * + * * @param filePath * to the object to check * @param session @@ -337,7 +337,7 @@ public class SshRepository extends AbstractSshBasedRepository { /* * (non-Javadoc) - * + * * @see org.apache.ivy.repository.Repository#get(java.lang.String, java.io.File) */ public void get(String source, File destination) throws IOException { @@ -373,7 +373,7 @@ public class SshRepository extends AbstractSshBasedRepository { /** * sets the list command to use for a directory listing listing must be only the filename and * each filename on a separate line - * + * * @param cmd * to use. default is "ls -1" */ @@ -422,7 +422,7 @@ public class SshRepository extends AbstractSshBasedRepository { * The file separator is the separator to use on the target system On a unix system it is '/', * but I don't know, how this is solved on different ssh implementations. Using the default * might be fine - * + * * @param fileSeparator * The fileSeparator to use. default '/' */ @@ -433,6 +433,8 @@ public class SshRepository extends AbstractSshBasedRepository { /** * A four digit string (e.g., 0644, see "man chmod", "man open") specifying the permissions of * the published files. + * + * @param permissions String */ public void setPublishPermissions(String permissions) { this.publishPermissions = permissions; @@ -448,10 +450,11 @@ public class SshRepository extends AbstractSshBasedRepository { /** * Not really streaming...need to implement a proper streaming approach? - * + * * @param resource * to stream * @return InputStream of the resource data + * @throws IOException if something goes wrong */ public InputStream openStream(SshResource resource) throws IOException { Session session = getSession(resource.getName()); diff --git a/src/java/org/apache/ivy/plugins/repository/vfs/VfsRepository.java b/src/java/org/apache/ivy/plugins/repository/vfs/VfsRepository.java index 65198119..914757f2 100644 --- a/src/java/org/apache/ivy/plugins/repository/vfs/VfsRepository.java +++ b/src/java/org/apache/ivy/plugins/repository/vfs/VfsRepository.java @@ -117,10 +117,10 @@ public class VfsRepository extends AbstractRepository { /** * Get a VfsResource - * + * * @param vfsURI * a String identifying a VFS Resource - * @throws IOException on failure + * @throws IOException on failure * @see "Supported File Systems in the jakarta-commons-vfs documentation" */ public Resource getResource(String vfsURI) throws IOException { @@ -129,12 +129,12 @@ public class VfsRepository extends AbstractRepository { /** * Transfer a VFS Resource from the repository to the local file system. - * + * * @param srcVfsURI * a String identifying the VFS resource to be fetched * @param destination * a File identifying the destination file - * @throws IOException on failure + * @throws IOException on failure * @see "Supported File Systems in the jakarta-commons-vfs documentation" */ public void get(String srcVfsURI, File destination) throws IOException { @@ -159,7 +159,7 @@ public class VfsRepository extends AbstractRepository { /** * Return a listing of the contents of a parent directory. Listing is a set of strings * representing VFS URIs. - * + * * @param vfsURI * providing identifying a VFS provided resource * @throws IOException @@ -188,14 +188,14 @@ public class VfsRepository extends AbstractRepository { /** * Transfer an Ivy resource to a VFS repository - * + * * @param source * a File identifying the local file to transfer to the repository * @param vfsURI * a String identifying the destination VFS Resource. * @param overwrite * whether to overwrite an existing resource. - * @throws IOException on failure. + * @throws IOException on failure. * @see "Supported File Systems in the jakarta-commons-vfs documentation" */ public void put(File source, String vfsURI, boolean overwrite) throws IOException { diff --git a/src/java/org/apache/ivy/plugins/repository/vfs/VfsResource.java b/src/java/org/apache/ivy/plugins/repository/vfs/VfsResource.java index 5a979248..444b2f93 100644 --- a/src/java/org/apache/ivy/plugins/repository/vfs/VfsResource.java +++ b/src/java/org/apache/ivy/plugins/repository/vfs/VfsResource.java @@ -83,7 +83,7 @@ public class VfsResource implements Resource { * Get a list of direct descendants of the given resource. Note that attempts to get a list of * children does not result in an error. Instead an error message is * logged and an empty ArrayList returned. - * + * * @return A ArrayList of VFSResources */ public List getChildren() { @@ -112,7 +112,7 @@ public class VfsResource implements Resource { /** * Get the name of the resource. - * + * * @return a String representing the Resource URL. */ public String getName() { @@ -126,9 +126,9 @@ public class VfsResource implements Resource { /** * The VFS FileName getURI method seems to have a bug in it where file: URIs will have 4 forward * slashes instead of 3. - * + * * @param vfsURI ditto - * @return a normalized String representing the VFS URI + * @return a normalized String representing the VFS URI */ public static String normalize(String vfsURI) { if (vfsURI == null) { @@ -143,7 +143,7 @@ public class VfsResource implements Resource { /** * Get the last modification time of the resource. - * + * * @return a long indicating last modified time. */ public long getLastModified() { @@ -153,7 +153,7 @@ public class VfsResource implements Resource { /** * Get the size of the resource - * + * * @return a long representing the size of the resource (in bytes). */ public long getContentLength() { @@ -163,7 +163,7 @@ public class VfsResource implements Resource { /** * Flag indicating whether a resource is available for querying - * + * * @return true if the resource is available for querying, false * otherwise. */ @@ -174,7 +174,7 @@ public class VfsResource implements Resource { /** * Return a flag indicating whether a provided VFS resource physically exists - * + * * @return true if the resource physically exists, false otherwise. */ public boolean physicallyExists() { diff --git a/src/java/org/apache/ivy/plugins/repository/vsftp/VsftpRepository.java b/src/java/org/apache/ivy/plugins/repository/vsftp/VsftpRepository.java index 1ec8f4f1..59b99e76 100644 --- a/src/java/org/apache/ivy/plugins/repository/vsftp/VsftpRepository.java +++ b/src/java/org/apache/ivy/plugins/repository/vsftp/VsftpRepository.java @@ -306,6 +306,11 @@ public class VsftpRepository extends AbstractRepository { * we compare the response with the expected message and deal with it. The problem is that this * is very specific to the version of vsftp used for the test, That's why expected messages are * obtained using overriddable protected methods. + * + * @param command String + * @param expectedResponse Pattern + * @param timeout long + * @throws IOException if something goes wrong */ protected void sendCommand(String command, Pattern expectedResponse, long timeout) throws IOException { @@ -638,7 +643,7 @@ public class VsftpRepository extends AbstractRepository { /** * Parses a ls -l line and transforms it in a resource - * + * * @param file ditto * @param responseLine ditto * @return Resource @@ -729,7 +734,7 @@ public class VsftpRepository extends AbstractRepository { /** * Sets the reuse connection time. The same connection will be reused if the time here does not * last between two commands. O indicates that the connection should never be reused - * + * * @param time long */ public void setReuseConnection(long time) { diff --git a/src/java/org/apache/ivy/plugins/resolver/AbstractSshBasedResolver.java b/src/java/org/apache/ivy/plugins/resolver/AbstractSshBasedResolver.java index 907ccb45..46be24a8 100644 --- a/src/java/org/apache/ivy/plugins/resolver/AbstractSshBasedResolver.java +++ b/src/java/org/apache/ivy/plugins/resolver/AbstractSshBasedResolver.java @@ -47,7 +47,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { /** * Sets the location of the Public Key file to use for authentication - * + * * @param filePath * full file path name */ @@ -57,7 +57,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { /** * Determines whether a local SSH agent may be used for authentication - * + * * @param allowedAgentUse * true if an agent may be used if available */ @@ -69,6 +69,8 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { * Optional password file. If set the repository will use it as an encrypted property file, to * load username and passwd entries, and to store them if the user choose to do so. Defaults to * user.dir/.ivy/[host].sftp.passwd, set it to null to disable this feature. + * + * @param passfile File */ public void setPassfile(File passfile) { getSshBasedRepository().setPassFile(passfile); @@ -89,7 +91,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { * set and password based login is used, user will be prompted for it the password can also be * set by using a full url for the pattern, like * "sftp://user:password@myserver.com/path/to/repos/[artifact].[ext]" - * + * * @param password * to use */ @@ -101,7 +103,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { * Sets the password to use for decrypting key file (if it is encrypted) if no password is set * and the keyfile is encrypted, the user will be prompted for the password if the keyfile is * passwordless, this parameter will be ignored if given - * + * * @param password * to use */ @@ -112,7 +114,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { /** * sets the user to use for the ssh communication the user can also be set by using a full url * for the pattern, like "ssh://user@myserver.com/path/to/repos/[artifact].[ext]" - * + * * @param user * on the target system */ @@ -123,7 +125,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { /** * sets the host to use for the ssh communication the host can also be set by using a full url * for the pattern, like "ssh://myserver.com/path/to/repos/[artifact].[ext]" - * + * * @param host * of the target system */ @@ -135,7 +137,7 @@ public abstract class AbstractSshBasedResolver extends RepositoryResolver { * sets the port to use for the ssh communication port 22 is default the port can also be set by * using a full url for the pattern, like * "sftp://myserver.com:8022/path/to/repos/[artifact].[ext]" - * + * * @param port * of the target system */ diff --git a/src/java/org/apache/ivy/plugins/resolver/DependencyResolver.java b/src/java/org/apache/ivy/plugins/resolver/DependencyResolver.java index 8bd4898b..80b98d35 100644 --- a/src/java/org/apache/ivy/plugins/resolver/DependencyResolver.java +++ b/src/java/org/apache/ivy/plugins/resolver/DependencyResolver.java @@ -46,7 +46,7 @@ public interface DependencyResolver { /** * Should only be used by configurator - * + * * @param name * the new name of the resolver */ @@ -57,8 +57,11 @@ public interface DependencyResolver { * latest one (i.e. a revision uniquely identifying the revision of a module in the current * environment - If this revision is not able to identify uniquely the revision of the module * outside of the current environment, then the resolved revision must begin by ##) - * - * @throws ParseException + * + * @param dd DependencyDescriptor + * @param data ResolveData + * @return ResolvedModuleRevision + * @throws ParseException if something goes wrong */ ResolvedModuleRevision getDependency(DependencyDescriptor dd, ResolveData data) throws ParseException; @@ -66,7 +69,7 @@ public interface DependencyResolver { /** * Finds the module descriptor for the specified DependencyDescriptor. If this resolver * can't find the module descriptor, null is returned. - * + * * @param dd * the dependency descriptor * @param data @@ -86,7 +89,7 @@ public interface DependencyResolver { * The returned DownloadReport is never null, and always contain an * {@link ArtifactDownloadReport} for each requested Artifact. *

    - * + * * @param artifacts * an array of artifacts to download. Must not be null. * @param options @@ -102,7 +105,7 @@ public interface DependencyResolver { * locates and downloads a set of artifacts. This method uses an {@link ArtifactOrigin}, and as * such is only used to materialize an already located Artifact. *

    - * + * * @param artifact * the location of the artifact to download. Must not be null. * @param options @@ -114,7 +117,7 @@ public interface DependencyResolver { /** * Returns true if the given artifact can be located by this resolver and actually * exist. - * + * * @param artifact * the artifact which should be tested. * @return true if the given artifact can be located by this resolver and actually @@ -125,7 +128,7 @@ public interface DependencyResolver { /** * Locates the given artifact and returns its location if it can be located by this resolver and * if it actually exists, or null in other cases. - * + * * @param artifact * the artifact which should be located * @return the artifact location, or null if it can't be located by this resolver @@ -148,7 +151,7 @@ public interface DependencyResolver { /** * Reports last artifact download failure as Messages - * + * * @param art Artifact */ void reportFailure(Artifact art); @@ -159,21 +162,26 @@ public interface DependencyResolver { // are registered in ivy too. /** - * List all the values the given token can take if other tokens are set as described in the - * otherTokenValues map. For instance, if token = "revision" and the map contains - * "organisation"->"foo" "module"->"bar" The results will be the list of revisions of the module - * bar from the org foo. + * List all the values the given token can take if other tokens are set as + * described in the otherTokenValues map. For instance, if + * token = "revision" and the map contains "organisation"->"foo" "module"->"bar" + * The results will be the list of revisions of the module bar from the org foo. *

    - * Note that listing does not take into account namespaces, and return raw information without - * any namespace transformation. The caller is responsible for calling namespace transformation - * with the Namespace returned by {@link #getNamespace()}. + * Note that listing does not take into account namespaces, and return raw + * information without any namespace transformation. The caller is + * responsible for calling namespace transformation with the Namespace + * returned by {@link #getNamespace()}. *

    + * + * @param token String + * @param otherTokenValues Map + * @return String[] */ String[] listTokenValues(String token, Map otherTokenValues); /** * Same as {@link #listTokenValues(String, Map)} but more generic. - * + * * @param tokens * the tokens of the query * @param criteria @@ -190,7 +198,7 @@ public interface DependencyResolver { /** * Returns the namespace associated with this resolver. - * + * * @return the namespace associated with this resolver. */ Namespace getNamespace(); @@ -202,7 +210,7 @@ public interface DependencyResolver { /** * Returns the {@link RepositoryCacheManager} used to manage the repository cache associated * with this dependency resolver. - * + * * @return the {@link RepositoryCacheManager} used to manage the repository cache associated * with this dependency resolver. */ diff --git a/src/java/org/apache/ivy/plugins/resolver/SshResolver.java b/src/java/org/apache/ivy/plugins/resolver/SshResolver.java index bdb5e986..3c68dcca 100644 --- a/src/java/org/apache/ivy/plugins/resolver/SshResolver.java +++ b/src/java/org/apache/ivy/plugins/resolver/SshResolver.java @@ -31,6 +31,8 @@ public class SshResolver extends AbstractSshBasedResolver { /** * A four digit string (e.g., 0644, see "man chmod", "man open") specifying the permissions of * the published files. + * + * @param permissions String */ public void setPublishPermissions(String permissions) { ((SshRepository) getRepository()).setPublishPermissions(permissions); @@ -39,7 +41,7 @@ public class SshResolver extends AbstractSshBasedResolver { /** * sets the path separator used on the target system. Not sure if this is used or if '/' is used * on all implementation. default is to use '/' - * + * * @param sep * file separator to use on the target system */ @@ -57,6 +59,8 @@ public class SshResolver extends AbstractSshBasedResolver { * the term %arg can be used in the command to substitute the path to be listed (e.g. * "ls -1 %arg | grep -v CVS" to get a listing without CVS directory) if %arg is not part of the * command, the path will be appended to the command default is: "ls -1" + * + * @param cmd String */ public void setListCommand(String cmd) { ((SshRepository) getRepository()).setListCommand(cmd); @@ -65,9 +69,11 @@ public class SshResolver extends AbstractSshBasedResolver { /** * set the command to check for existence of a file the command has to be a shell command * working on the target system and has to create an exit status of 0 for an existent file and - * <> 0 for a non existing file given as argument the term %arg can be used in the command to - * substitute the path to be listed if %arg is not part of the command, the path will be appended - * to the command default is: "ls" + * <> 0 for a non existing file given as argument the term %arg can be used in the command + * to substitute the path to be listed if %arg is not part of the command, the path will be + * appended to the command default is: "ls" + * + * @param cmd String */ public void setExistCommand(String cmd) { ((SshRepository) getRepository()).setExistCommand(cmd); @@ -78,6 +84,8 @@ public class SshResolver extends AbstractSshBasedResolver { * command working on the target system and has to create a directory with the given argument * the term %arg can be used in the command to substitute the path to be listed if %arg is not * part of the command, the path will be appended to the command default is: "mkdir" + * + * @param cmd String */ public void setCreateDirCommand(String cmd) { ((SshRepository) getRepository()).setExistCommand(cmd); diff --git a/src/java/org/apache/ivy/plugins/resolver/WorkspaceChainResolver.java b/src/java/org/apache/ivy/plugins/resolver/WorkspaceChainResolver.java index a3662cfe..a1028d17 100644 --- a/src/java/org/apache/ivy/plugins/resolver/WorkspaceChainResolver.java +++ b/src/java/org/apache/ivy/plugins/resolver/WorkspaceChainResolver.java @@ -20,9 +20,9 @@ package org.apache.ivy.plugins.resolver; import org.apache.ivy.core.settings.IvySettings; /** - * Resolver which decorate normal resolver so that the workspace resolver can hijack the resolve - * process
    - * NB : it is for internal usage of Ivy only! + * Resolver which decorate normal resolver so that the workspace resolver can + * hijack the resolveprocess + *

    NB : it is for internal usage of Ivy only!

    */ public class WorkspaceChainResolver extends ChainResolver { diff --git a/src/java/org/apache/ivy/plugins/resolver/packager/PackagerCacheEntry.java b/src/java/org/apache/ivy/plugins/resolver/packager/PackagerCacheEntry.java index a7fe87a0..b88f0e57 100644 --- a/src/java/org/apache/ivy/plugins/resolver/packager/PackagerCacheEntry.java +++ b/src/java/org/apache/ivy/plugins/resolver/packager/PackagerCacheEntry.java @@ -81,14 +81,14 @@ public class PackagerCacheEntry { /** * Attempt to build this entry. - * + * * @param packagerResource * packager metadata resource * @param properties * a map of properties to pass to the child Ant build responsible for dependency * packaging - * - * @throws IllegalStateException + * + * @throws IOException * if this entry has already been built */ public synchronized void build(Resource packagerResource, Map properties) throws IOException { @@ -176,6 +176,8 @@ public class PackagerCacheEntry { /** * Has this entry been successfully built? + * + * @return boolean */ public synchronized boolean isBuilt() { return this.built; @@ -183,7 +185,9 @@ public class PackagerCacheEntry { /** * Get a built artifact. - * + * + * @param artifact ditto + * @return ResolvedResource * @throws IllegalStateException * if this entry's built has not (yet) completed successfully */ diff --git a/src/java/org/apache/ivy/plugins/resolver/packager/PackagerResolver.java b/src/java/org/apache/ivy/plugins/resolver/packager/PackagerResolver.java index 6a12ba14..26ed972c 100644 --- a/src/java/org/apache/ivy/plugins/resolver/packager/PackagerResolver.java +++ b/src/java/org/apache/ivy/plugins/resolver/packager/PackagerResolver.java @@ -36,10 +36,11 @@ import org.apache.ivy.util.Message; /** * Resolver that performs a "build" operation to resolve artifacts. - * + * *

    * The resolver is configured with a base URL, from which the "ivy.xml" and "packager.xml" files are * resolved. The latter file contains instructions describing how to build the actual artifacts. + *

    */ public class PackagerResolver extends URLResolver { @@ -93,6 +94,8 @@ public class PackagerResolver extends URLResolver { /** * Set root directory under which builds take place. + * + * @param buildRoot File */ public void setBuildRoot(File buildRoot) { this.buildRoot = buildRoot; @@ -100,6 +103,8 @@ public class PackagerResolver extends URLResolver { /** * Returns root directory under which builds take place. + * + * @return File */ public File getBuildRoot() { return buildRoot; @@ -107,6 +112,8 @@ public class PackagerResolver extends URLResolver { /** * Set resource cache directory. + * + * @param resourceCache File */ public void setResourceCache(File resourceCache) { this.resourceCache = resourceCache; @@ -114,6 +121,8 @@ public class PackagerResolver extends URLResolver { /** * Get resource cache directory. + * + * @return File */ public File getResourceCache() { return resourceCache; @@ -121,6 +130,8 @@ public class PackagerResolver extends URLResolver { /** * Set base resource override URL pattern. + * + * @param resourceURL String */ public void setResourceURL(String resourceURL) { this.resourceURL = resourceURL; @@ -128,6 +139,8 @@ public class PackagerResolver extends URLResolver { /** * Set pattern for locating "packager.xml" files. + * + * @param pattern String */ public void setPackagerPattern(String pattern) { ArrayList list = new ArrayList(); @@ -137,6 +150,8 @@ public class PackagerResolver extends URLResolver { /** * Set whether to preserve build directories. Default is false. + * + * @param preserve boolean */ public void setPreserveBuildDirectories(boolean preserve) { this.preserve = preserve; @@ -144,6 +159,8 @@ public class PackagerResolver extends URLResolver { /** * Set whether to enable restricted mode. Default is true. + * + * @param restricted boolean */ public void setRestricted(boolean restricted) { this.restricted = restricted; @@ -151,6 +168,8 @@ public class PackagerResolver extends URLResolver { /** * Set whether to run ant with the -verbose flag. Default is false. + * + * @param verbose boolean */ public void setVerbose(boolean verbose) { this.verbose = verbose; @@ -158,6 +177,8 @@ public class PackagerResolver extends URLResolver { /** * Set whether to run ant with the -quiet flag. Default is false. + * + * @param quiet boolean */ public void setQuiet(boolean quiet) { this.quiet = quiet; @@ -165,6 +186,8 @@ public class PackagerResolver extends URLResolver { /** * Set whether to validate downloaded packager.xml files. Default is true. + * + * @param validate boolean */ public void setValidate(boolean validate) { this.validate = validate; @@ -185,7 +208,7 @@ public class PackagerResolver extends URLResolver { /** * Sets a property to be passed to the child Ant build responsible for packaging the dependency. - * + * * @param propertyKey * the property to pass * @param propertyValue diff --git a/src/java/org/apache/ivy/plugins/version/VersionMatcher.java b/src/java/org/apache/ivy/plugins/version/VersionMatcher.java index 41f95332..184b28e4 100644 --- a/src/java/org/apache/ivy/plugins/version/VersionMatcher.java +++ b/src/java/org/apache/ivy/plugins/version/VersionMatcher.java @@ -45,7 +45,7 @@ public interface VersionMatcher { /** * Indicates if the given asked ModuleRevisionId should be considered as dynamic for the current * VersionMatcher or not. - * + * * @param askedMrid * the dependency module revision id as asked by a module * @return true if this revision is considered as a dynamic one, false otherwise @@ -55,7 +55,7 @@ public interface VersionMatcher { /** * Indicates if this version matcher considers that the module revision found matches the asked * one. - * + * * @param askedMrid ModuleRevisionId * @param foundMrid ModuleRevisionId * @return boolean @@ -66,7 +66,9 @@ public interface VersionMatcher { * Indicates if this VersionMatcher needs module descriptors to determine if a module revision * matches the asked one. Note that returning true in this method may imply big performance * issues. - * + * + * @param askedMrid ModuleRevisionId + * @param foundMrid ModuleRevisionId * @return boolean */ public boolean needModuleDescriptor(ModuleRevisionId askedMrid, ModuleRevisionId foundMrid); @@ -76,7 +78,7 @@ public interface VersionMatcher { * method can be called even needModuleDescriptor(ModuleRevisionId askedMrid, ModuleRevisionId * foundMrid) returns false, so it is required to implement it in any case, a usual default * implementation being: return accept(askedMrid, foundMD.getResolvedModuleRevisionId()); - * + * * @param askedMrid ModuleRevisionId * @param foundMD ModuleDescriptor * @return boolean @@ -88,7 +90,7 @@ public interface VersionMatcher { * should be considered the greater. If there is not enough information to know which one is the * greater, the dynamic one should be considered greater and this method should return 0. This * method should never be called with a askedMrid for which isDynamic returns false. - * + * * @param askedMrid * the dynamic revision to compare * @param foundMrid @@ -103,7 +105,7 @@ public interface VersionMatcher { /** * Returns the version matcher name identifying this version matcher - * + * * @return the version matcher name identifying this version matcher */ public String getName(); diff --git a/src/java/org/apache/ivy/util/FileUtil.java b/src/java/org/apache/ivy/util/FileUtil.java index aca40072..c938007d 100644 --- a/src/java/org/apache/ivy/util/FileUtil.java +++ b/src/java/org/apache/ivy/util/FileUtil.java @@ -57,9 +57,9 @@ public final class FileUtil { // Utility class } - // according to tests by users, 64kB seems to be a good value for the buffer used during copy + // according to tests by users, 64kB seems to be a good value for the buffer used during copy; // further improvements could be obtained using NIO API - private static final int BUFFER_SIZE = 64 * 1024; + private static final int BUFFER_SIZE = 64 * 1024; private static final byte[] EMPTY_BUFFER = new byte[0]; @@ -67,13 +67,12 @@ public final class FileUtil { public static void symlinkInMass(Map destToSrcMap, boolean overwrite) throws IOException { - - // This pattern could be more forgiving if somebody wanted it to be... - // ...but this should satisfy 99+% of all needs, without letting unsafe operations be done. + // This pattern could be more forgiving if somebody wanted it to be... but this should + // satisfy 99+% of all needs, without letting unsafe operations be done. // If you paths is not supported, you then skip this mass option. // NOTE: A space inside the path is allowed (I can't control other programmers who like them - // in their working directory names)... - // but trailing spaces on file names will be checked otherwise and refused. + // in their working directory names)... but trailing spaces on file names will be checked + // otherwise and refused. try { StringBuffer sb = new StringBuffer(); @@ -456,10 +455,14 @@ public final class FileUtil { /** * Returns a list of Files composed of all directories being parent of file and child of root + - * file and root themselves. Example: getPathFiles(new File("test"), new - * File("test/dir1/dir2/file.txt")) => {new File("test/dir1"), new File("test/dir1/dir2"), new - * File("test/dir1/dir2/file.txt") } Note that if root is not an ancestor of file, or if root is - * null, all directories from the file system root will be returned. + * file and root themselves. Example: getPathFiles(new File("test"), new + * File("test/dir1/dir2/file.txt")) => {new File("test/dir1"), new File("test/dir1/dir2"), + * new File("test/dir1/dir2/file.txt") } Note that if root is not an ancestor of file, or + * if root is null, all directories from the file system root will be returned. + * + * @param root File + * @param file File + * @return List<File> */ public static List getPathFiles(File root, File file) { List ret = new ArrayList(); @@ -475,15 +478,13 @@ public final class FileUtil { } /** - * Returns a collection of all Files being contained in the given directory, recursively, - * including directories. - * * @param dir * The directory from which all files, including files in subdirectory) are * extracted. * @param ignore * a Collection of filenames which must be excluded from listing - * @return A collection containing all the files of the given directory and it's subdirectories. + * @return a collection containing all the files of the given directory and it's subdirectories, + * recursively. */ public static Collection listAll(File dir, Collection ignore) { return listAll(dir, new ArrayList(), ignore); @@ -534,12 +535,9 @@ public final class FileUtil { * Unlike {@link File#getCanonicalPath()} this method specifically does not resolve symbolic * links. * - * @param path - * the path to be normalized. + * @param path the path to be normalized. * @return the normalized version of the path. - * - * @throws java.lang.NullPointerException - * if path is null. + * @throws NullPointerException if path is null. */ public static File normalize(final String path) { Stack s = new Stack(); @@ -577,21 +575,20 @@ public final class FileUtil { /** * Dissect the specified absolute path. * - * @param path - * the path to dissect. + * @param path the path to dissect. * @return String[] {root, remaining path}. - * @throws java.lang.NullPointerException - * if path is null. + * @throws NullPointerException if path is null. * @since Ant 1.7 */ private static String[] dissect(String path) { char sep = File.separatorChar; path = path.replace('/', sep).replace('\\', sep); - // // make sure we are dealing with an absolute path - // if (!isAbsolutePath(path)) { - // throw new BuildException(path + " is not an absolute path"); - // } + /* // make sure we are dealing with an absolute path + * if (!isAbsolutePath(path)) { + * throw new BuildException(path + " is not an absolute path"); + * } + */ String root = null; int colon = path.indexOf(':'); if (colon > 0) { // && (ON_DOS || ON_NETWARE)) { @@ -627,8 +624,8 @@ public final class FileUtil { /** * Get the length of the file, or the sum of the children lengths if it is a directory * - * @param file - * @return + * @param file File + * @return long */ public static long getFileLength(File file) { long l = 0; diff --git a/src/java/org/apache/ivy/util/StringUtils.java b/src/java/org/apache/ivy/util/StringUtils.java index 11518722..01f31dc1 100644 --- a/src/java/org/apache/ivy/util/StringUtils.java +++ b/src/java/org/apache/ivy/util/StringUtils.java @@ -47,8 +47,7 @@ public final class StringUtils { * will try to be as precise as possible, handling cases where e.getMessage() is not meaningful, * like {@link NullPointerException} for instance. * - * @param t - * the throwable to get the error message from + * @param t the throwable to get the error message from * @return the error message of the given exception */ public static String getErrorMessage(Throwable t) { @@ -89,7 +88,7 @@ public final class StringUtils { * Example: * * 
    -     * join(new String[] {"one", "two", "three"}, ", ") -> "one, two, three"
+     * join(new String[] {"one", "two", "three"}, ", ") -> "one, two, three"
      *
    * * @param objs @@ -110,7 +109,9 @@ public final class StringUtils { } // basic string codec (same algo as CVS passfile, inspired by ant CVSPass class - /** Array contain char conversion data */ + /** + * Array containing char conversion data + */ private static final char[] SHIFTS = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 114, 120, 53, 79, 96, 109, 72, 108, 70, 64, 76, 67, 116, 74, 68, 87, 111, 52, 75, 119, 49, 34, 82, 81, 95, 65, @@ -130,7 +131,7 @@ public final class StringUtils { * Encrypt the given string in a way which anybody having access to this method algorithm can * easily decrypt. This is useful only to avoid clear string storage in a file for example, but * shouldn't be considered as a real mean of security. This only works with simple characters - * (char < 256). + * (char < 256). * * @param str * the string to encrypt diff --git a/src/java/org/apache/ivy/util/XMLHelper.java b/src/java/org/apache/ivy/util/XMLHelper.java index 78d691e5..894ccc85 100644 --- a/src/java/org/apache/ivy/util/XMLHelper.java +++ b/src/java/org/apache/ivy/util/XMLHelper.java @@ -95,6 +95,9 @@ public abstract class XMLHelper { /** * Convert an URL to a valid systemId according to RFC 2396. + * + * @param url URL + * @return String */ public static String toSystemId(URL url) { try { @@ -105,9 +108,9 @@ public abstract class XMLHelper { } // IMPORTANT: validation errors are only notified to the given handler, and - // do not cause exception - // implement warning error and fatalError methods in handler to be informed - // of validation errors + // do not cause exception implement warning error and fatalError methods in + // handler to be informed of validation errors + public static void parse(URL xmlURL, URL schema, DefaultHandler handler) throws SAXException, IOException, ParserConfigurationException { parse(xmlURL, schema, handler, null); @@ -177,12 +180,12 @@ public abstract class XMLHelper { /** * Escapes invalid XML characters in the given character data using XML entities. For the - * moment, only the following characters are being escaped: (<), (&), (') and ("). - * - * Remark: we don't escape the (>) character to keep the readability of the configuration - * mapping! The XML spec only requires that the (&) and (<) characters are being escaped inside - * character data. - * + * moment, only the following characters are being escaped: (<), (&), (') and ("). + * + * Remark: we don't escape the (>) character to keep the readability of the configuration + * mapping! The XML spec only requires that the (&) and (<) characters are being escaped + * inside character data. + * * @param text * the character data to escape * @return the escaped character data diff --git a/src/java/org/apache/ivy/util/filter/FilterHelper.java b/src/java/org/apache/ivy/util/filter/FilterHelper.java index 9e79e130..a665a002 100644 --- a/src/java/org/apache/ivy/util/filter/FilterHelper.java +++ b/src/java/org/apache/ivy/util/filter/FilterHelper.java @@ -54,19 +54,19 @@ public final class FilterHelper { } /** - * Returns a new collection containing only the items from the given collection, which are - * accepted by the filter. - * + * @param The type parameter * @param col * The collection to filter. * @param filter * The filter to use. - * @return A new collection instance containing the only the instance accepted by the filter. + * @return a new collection instance containing the only the the items from the given + * collection, which are accepted by the filter. * - *
    - * Comment: We could have used - * Commons-Collections - * facility for this. If we accepted to add dependencies on third party jars. + *

    + * Comment: We could have used + * Commons Collections facility for + * this, if we accepted additional dependencies on third party jars. + *

    */ public static Collection filter(Collection col, Filter filter) { if (filter == null) { diff --git a/src/java/org/apache/ivy/util/url/URLHandler.java b/src/java/org/apache/ivy/util/url/URLHandler.java index 96b51d91..b429ef91 100644 --- a/src/java/org/apache/ivy/util/url/URLHandler.java +++ b/src/java/org/apache/ivy/util/url/URLHandler.java @@ -83,48 +83,44 @@ public interface URLHandler { /** * Please prefer getURLInfo when several infos are needed. - * - * @param url - * the url to check + * + * @param url the url to check * @return true if the target is reachable */ public boolean isReachable(URL url); /** * Please prefer getURLInfo when several infos are needed. - * - * @param url - * the url to check + * + * @param url the url to check + * @param timeout the timeout in milliseconds * @return true if the target is reachable */ public boolean isReachable(URL url, int timeout); /** - * Returns the length of the target if the given url is reachable, and without error code in - * case of http urls. Please prefer getURLInfo when several infos are needed. - * - * @param url - * the url to check - * @return the length of the target if available, 0 if not reachable + * Please prefer getURLInfo when several infos are needed. + * + * @param url the url to check + * @return the length of the target if the given url is reachable, 0 otherwise. No error code in + * case of http urls. */ public long getContentLength(URL url); /** - * Returns the length of the target if the given url is reachable, and without error code in - * case of http urls. - * * @param url * the url to check * @param timeout - * the maximum time before considering an url is not reachable a timeout of zero - * indicates no timeout - * @return the length of the target if available, 0 if not reachable + * the maximum time before considering an url is not reachable a + * timeout of zero indicates no timeout + * @return the length of the target if the given url is reachable, 0 otherwise. No error code in + * case of http urls. */ public long getContentLength(URL url, int timeout); /** * Please prefer getURLInfo when several infos are needed. - * + * * @param url * the url to check * @return last modified timestamp of the given url @@ -133,33 +129,28 @@ public interface URLHandler { /** * Please prefer getURLInfo when several infos are needed. - * - * @param url - * the url to check + * + * @param url the url to check + * @param timeout the timeout in milliseconds * @return last modified timestamp of the given url */ public long getLastModified(URL url, int timeout); /** - * Returns the URLInfo of the given url or a {@link #UNAVAILABLE} instance, if the url is not - * reachable. - * * @param url * The url from which information is retrieved. - * @return The URLInfo extracted from the given url, or {@link #UNAVAILABLE} when the url is not - * available. + * @return The URLInfo extracted from the given url, or {@link #UNAVAILABLE} instance when the + * url is not reachable. */ public URLInfo getURLInfo(URL url); /** - * never returns null, return UNAVAILABLE when url is not reachable - * * @param url * The url from which information is retrieved. * @param timeout * The timeout in milliseconds. * @return The URLInfo extracted from the given url, or {@link #UNAVAILABLE} when the url is not - * available. + * reachable, never null. */ public URLInfo getURLInfo(URL url, int timeout); diff --git a/src/java/org/apache/ivy/util/url/URLHandlerRegistry.java b/src/java/org/apache/ivy/util/url/URLHandlerRegistry.java index 8bffe976..cd78811a 100644 --- a/src/java/org/apache/ivy/util/url/URLHandlerRegistry.java +++ b/src/java/org/apache/ivy/util/url/URLHandlerRegistry.java @@ -39,7 +39,7 @@ public final class URLHandlerRegistry { /** * This method is used to get appropriate http downloader depending on Jakarta Commons * HttpClient availability in classpath, or simply use jdk url handling in other cases. - * + * * @return most accurate http downloader */ public static URLHandler getHttp() {