Updated API docs and release notes for Artifact Query API

gradle · May 18, 2014 · de7abf9 · de7abf9
1 parent 9a36332
commit de7abf9
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 36 deletions.
diff --git a/subprojects/core/src/main/groovy/org/gradle/api/artifacts/query/ArtifactResolutionQuery.java b/subprojects/core/src/main/groovy/org/gradle/api/artifacts/query/ArtifactResolutionQuery.java
@@ -24,6 +24,23 @@
 /**
  * A builder to construct a query that can resolve selected software artifacts of the specified components.
  *
+ * <pre autoTested=''>
+ *  apply plugin: 'java'
+ *
+ *  task resolveCompileSources << {
+ *      def componentIds = configurations.compile.incoming.resolutionResult.allDependencies.collect { it.selected.id }
+ *
+ *      def result = dependencies.createArtifactResolutionQuery()
+ *                          .forComponents(componentIds)
+ *                          .withArtifacts(JvmLibrary, SourcesArtifact, JavadocArtifact)
+ *                          .execute()
+ *
+ *      for (component in result.resolvedComponents) {
+ *          component.getArtifacts(SourcesArtifact).each { println "Source artifact for ${component.id}: ${it.file}" }
+ *      }
+ *  }
+ * </pre>
+ *
  * @since 2.0
  */
 @Incubating

diff --git a/subprojects/docs/src/docs/dsl/dsl.xml b/subprojects/docs/src/docs/dsl/dsl.xml
@@ -157,6 +157,9 @@
             <tr>
                 <td>org.gradle.api.artifacts.ResolutionStrategy</td>
             </tr>
+            <tr>
+                <td>org.gradle.api.artifacts.query.ArtifactResolutionQuery</td>
+            </tr>
             <tr>
                 <td>org.gradle.api.dsl.ConventionProperty</td>
             </tr>

diff --git a/subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.dsl.DependencyHandler.xml b/subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.dsl.DependencyHandler.xml
@@ -41,6 +41,9 @@
             <tr>
                 <td>components</td>
             </tr>
+            <tr>
+                <td>createArtifactResolutionQuery</td>
+            </tr>
         </table>
     </section>
 </section>
diff --git a/subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.query.ArtifactResolutionQuery.xml b/subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.query.ArtifactResolutionQuery.xml
@@ -0,0 +1,47 @@
+<!--
+  ~ Copyright 2014 the original author or authors.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~      http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<section>
+    <section>
+        <title>Properties</title>
+        <table>
+            <thead>
+                <tr>
+                    <td>Name</td>
+                </tr>
+            </thead>
+        </table>
+    </section>
+    <section>
+        <title>Methods</title>
+        <table>
+            <thead>
+                <tr>
+                    <td>Name</td>
+                </tr>
+            </thead>
+            <tr>
+                <td>forComponents</td>
+            </tr>
+            <tr>
+                <td>withArtifacts</td>
+            </tr>
+            <tr>
+                <td>execute</td>
+            </tr>
+        </table>
+    </section>
+</section>
diff --git a/subprojects/docs/src/docs/release/notes.md b/subprojects/docs/src/docs/release/notes.md
@@ -6,52 +6,31 @@ Here are the new features introduced in this Gradle release.
 
 Gradle now uses Groovy 2.2.2 to compile and running build scripts and plugins.
 
-### New API for artifact resolution (i)
+### New API for resolving source and javadoc artifacts (i)
 
 Gradle 2.0 introduces a new, incubating API for resolving component artifacts. With this addition, Gradle now offers separate dedicated APIs for resolving
-components and artifacts. (Component resolution is mainly concerned with computing the dependency graph, whereas artifact resolution is
-mainly concerned with locating and downloading artifacts.) The entry points to the component and artifact resolution APIs are `configuration.incoming` and
-`dependencies.createArtifactResolutionQuery()`, respectively.
+components and artifacts. The entry point to the new 'artifact query' API is `dependencies.createArtifactResolutionQuery()`.
 
-TODO: This API examples are out of date. Add new tested samples to the Javadoc or Userguide and link instead
+Presently, this feature is limited to the resolution of `SourcesArtifact` and `JavadocArtifact` artifacts for a `JvmLibrary` components.
+Over time this will be expanded to permit querying of other component and artifact types.
 
-Here is an example usage of the new API:
+For example, to get the source artifacts for all 'compile' dependencies:
 
-    def query = dependencies.createArtifactResolutionQuery()
-        .forComponent("org.springframework", "spring-core", "3.2.3.RELEASE")
-        .forArtifacts(JvmLibrary)
+    task resolveSources << {
+        def componentIds = configurations.compile.incoming.resolutionResult.allDependencies.collect { it.selected.id }
 
-    def result = query.execute() // artifacts are downloaded at this point
+        def result = dependencies.createArtifactResolutionQuery()
+                          .forComponents(componentIds)
+                          .withArtifacts(JvmLibrary, SourcesArtifact, JavadocArtifact)
+                          .execute()
 
-    for (component in result.components) {
-        assert component instanceof JvmLibrary
-        println component.id
-        component.sourceArtifacts.each { println it.file }
-        component.javadocArtifacts.each { println it.file }
-    }
-
-    assert result.unresolvedComponents.isEmpty()
-
-Artifact resolution can be limited to selected artifact types:
-
-    def query = dependencies.createArtifactResolutionQuery()
-        .forComponent("org.springframework", "spring-core", "3.2.3.RELEASE")
-        .forArtifacts(JvmLibrary, JvmLibrarySourcesArtifact)
-
-    def result = query.execute()
-
-    for (component in result.components) {
-        assert !component.sourceArtifacts.isEmpty()
-        assert component.javadocArtifacts.isEmpty()
+        for (component in result.resolvedComponents) {
+            component.getArtifacts(SourcesArtifact).each { println "Source artifact for ${component.id}: ${it.file}" }
+        }
     }
 
-Artifacts for many components can be resolved together:
-
-    def query = dependencies.createArtifactResolutionQuery()
-        .forComponents(setOfComponentIds)
-        .forArtifacts(JvmLibrary)
 
-So far, only one component type (`JvmLibrary`) is available, but others will follow, also for platforms other than the JVM.
+For an example usage of the new API, see <a href="dsl/org.gradle.api.artifacts.query.ArtifactResolutionQuery.html">the DSL Reference</a>.
 
 ### Accessing Ivy extra info from component metadata rules