From de7abf924fb4a17615bcb7ceec1bb5a685fdc715 Mon Sep 17 00:00:00 2001 From: daz Date: Sun, 18 May 2014 09:14:57 +1200 Subject: [PATCH] Updated API docs and release notes for Artifact Query API --- .../query/ArtifactResolutionQuery.java | 17 +++++++ subprojects/docs/src/docs/dsl/dsl.xml | 3 ++ ...le.api.artifacts.dsl.DependencyHandler.xml | 3 ++ ...rtifacts.query.ArtifactResolutionQuery.xml | 47 +++++++++++++++++ subprojects/docs/src/docs/release/notes.md | 51 ++++++------------- 5 files changed, 85 insertions(+), 36 deletions(-) create mode 100644 subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.query.ArtifactResolutionQuery.xml 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 index cf60ce445806..e2a6f74f5b74 100644 --- 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. * + * 
+ *  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}" }
+ *      }
+ *  }
+ *
+ * * @since 2.0 */ @Incubating diff --git a/subprojects/docs/src/docs/dsl/dsl.xml b/subprojects/docs/src/docs/dsl/dsl.xml index 18f5bfdad8c4..3c9ea89df3a2 100644 --- a/subprojects/docs/src/docs/dsl/dsl.xml +++ b/subprojects/docs/src/docs/dsl/dsl.xml @@ -157,6 +157,9 @@ org.gradle.api.artifacts.ResolutionStrategy + + org.gradle.api.artifacts.query.ArtifactResolutionQuery + org.gradle.api.dsl.ConventionProperty 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 index 1acf8f3a4dff..b99fc9903784 100644 --- 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 @@ components + + createArtifactResolutionQuery + \ No newline at end of file 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 new file mode 100644 index 000000000000..18295ee70f38 --- /dev/null +++ b/subprojects/docs/src/docs/dsl/org.gradle.api.artifacts.query.ArtifactResolutionQuery.xml @@ -0,0 +1,47 @@ + + +
+
+ Properties + + + + + + +
Name
+
+
+ Methods + + + + + + + + + + + + + + + +
Name
forComponents
withArtifacts
execute
+
+
\ No newline at end of file diff --git a/subprojects/docs/src/docs/release/notes.md b/subprojects/docs/src/docs/release/notes.md index bc596e8c5a22..a825e8d78df3 100644 --- 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 the DSL Reference. ### Accessing Ivy extra info from component metadata rules