{"action":"created","comment":{"url":"https://api.github.com/repos/gradle/gradle/pulls/comments/95343495","pull_request_review_id":15888312,"id":95343495,"diff_hunk":"@@ -0,0 +1,277 @@\n+<!--\n+  ~ Copyright 2016 the original author or authors.\n+  ~\n+  ~ Licensed under the Apache License, Version 2.0 (the \"License\");\n+  ~ you may not use this file except in compliance with the License.\n+  ~ You may obtain a copy of the License at\n+  ~\n+  ~      http://www.apache.org/licenses/LICENSE-2.0\n+  ~\n+  ~ Unless required by applicable law or agreed to in writing, software\n+  ~ distributed under the License is distributed on an \"AS IS\" BASIS,\n+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+  ~ See the License for the specific language governing permissions and\n+  ~ limitations under the License.\n+  -->\n+\n+<chapter id='java_library_plugin'>\n+    <title>The Java Library Plugin</title>\n+\n+    <para>The Java Library plugin expands the capabilities of the Java plugin by providing specific knowledge about Java libraries. In particular, a Java\n+        library exposes an API to consumers. All the source sets, tasks and configurations exposed by the Java plugin are implicitly available when using\n+        this plugin.\n+    </para>\n+\n+    <section id=\"sec:java_library_usage\">\n+        <title>Usage</title>\n+        <para>To use the Java Library plugin, include the following in your build script:</para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"Using the Java Library plugin\">\n+            <sourcefile file=\"build.gradle\" snippet=\"use-plugin\"/>\n+        </sample>\n+    </section>\n+\n+    <section id=\"sec:java_library_separation\">\n+        <title>API and implementation separation</title>\n+        <para>The key difference between the standard Java plugin and the Java Library plugin is that the latter introduces the concept of\n+            an <firstterm>API</firstterm> exposed to consumers. A library is a Java component meant to be consumed by other components.\n+            It's a very common use case in multi-project builds, but also as soon as you have external dependencies: by definition, any\n+            dependency is a Java library.\n+        </para>\n+        <para>\n+            The plugin exposes two <firstterm>configurations</firstterm> that can be used to declare dependencies:\n+            <literal>api</literal>\n+            and <literal>implementation</literal>. The <literal>api</literal> configuration should be used to declare dependencies which\n+            are exported by the library API, whereas the <literal>implementation</literal> configuration should be used to declare dependencies\n+            which are internal to the component.\n+        </para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"Declaring API and implementation dependencies\">\n+            <sourcefile file=\"build.gradle\" snippet=\"dependencies\"/>\n+        </sample>\n+        <para>Dependencies appearing in the <literal>api</literal> configurations will be transitively exposed to consumers of the library, and\n+            as such will appear on the compile classpath of consumers. Dependencies found in the <literal>implementation</literal> configuration will,\n+            on the other hand, not be exposed to consumers, and therefore not leak into their own compile classpath. This comes with several benefits:\n+        </para>\n+        <itemizedlist>\n+            <listitem>dependencies do not leak into the compile classpath of consumers anymore, so you will never accidently depend on a transitive dependency</listitem>\n+            <listitem>faster compilation thanks to reduced classpath size</listitem>\n+            <listitem>less recompilations when implementation dependencies change: consumers would not need to be recompiled</listitem>\n+            <listitem>cleaner publishing: when used in conjunction with the new <literal>maven-publish</literal> plugin, Java libraries produce POM files\n+                representing exactly what is required to compile against the library, or use at runtime (in other words, don't mix what is needed to compile\n+                the library itself and what is needed to compile against the library).\n+            </listitem>\n+        </itemizedlist>\n+        <note>The <literal>compile</literal> configuration still exists but should not be used as it will not offer the guarantees that the\n+            <literal>api</literal>\n+            and <literal>implementation</literal> configurations provide.\n+        </note>\n+    </section>\n+\n+    <section id=\"sec:java_library_recognizing_dependencies\">\n+        <title>Recognizing API and implementation dependencies</title>\n+        <para>As soon as we want to separate API and implementation dependencies, we reckon some guidelines as to make the difference between the two.\n+            Basically, an API dependency is a type that is exposed in the library binary interface, often referred to ABI (Application Binary Interface).\n+            This includes, but is not limited to:\n+        </para>\n+        <itemizedlist>\n+            <listitem>types used in super classes or interfaces</listitem>\n+            <listitem>types used in public method parameters, including generic parameter types (where <firstterm>public</firstterm> is something visible to compilers, so public, protected and\n+                package-private members in the Java world)\n+            </listitem>\n+            <listitem>types used in public fields</listitem>\n+            <listitem>public annotation types</listitem>\n+        </itemizedlist>\n+        <para>In opposition, any type that is used in the following list is irrelevant to the ABI, and therefore should be declared as <literal>implementation</literal> dependencies:\n+        </para>\n+        <itemizedlist>\n+            <listitem>types exclusively used in method bodies</listitem>\n+            <listitem>types exclusively used in private members</listitem>\n+            <listitem>types exclusively found in internal classes (future versions of Gradle will let you declare which packages belong to the public API)</listitem>\n+        </itemizedlist>\n+        <para>In the following sample, we can make the difference between an API dependency and an implementation dependency:</para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"Imports found in a class\">\n+            <sourcefile file=\"src/main/java/org/gradle/HttpClientWrapper.java\" snippet=\"imports\"/>\n+        </sample>\n+        <para>We can see that our class imports third party classes, but imports alone won't tell us if a dependency is an API or implementation dependency.\n+            For this, we need to look at the methods. The following method used <literal>HttpClient</literal> as a parameter, so it belongs to the public API:\n+        </para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"A dependency type is used in the public API\">\n+            <sourcefile file=\"src/main/java/org/gradle/HttpClientWrapper.java\" snippet=\"api-dependency\"/>\n+        </sample>\n+        <para>On the other hand, the <literal>ExceptionUtils</literal> type, coming from the <literal>commons-lang</literal> library, is only used in a method\n+            body, so it's an implementation dependency:\n+        </para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"A dependency type is used in the method bodies only\">\n+            <sourcefile file=\"src/main/java/org/gradle/HttpClientWrapper.java\" snippet=\"implementation-dependency\"/>\n+        </sample>\n+        <para>Therefore, we can deduce that <literal>commons-httpclient</literal> is an API dependency, whereas <literal>commons-lang</literal> is an implementation\n+            dependency, which directly translates into the build file:\n+        </para>\n+        <sample id=\"useJavaLibraryPlugin\" dir=\"java-library/quickstart\" title=\"Declaring API and implementation dependencies\">\n+            <sourcefile file=\"build.gradle\" snippet=\"dependencies\"/>\n+        </sample>\n+        <para>It's in general safer to assume that a dependency is an implementation dependency only: leakage of implementation types to consumers would","path":"subprojects/docs/src/docs/userguide/javaLibraryPlugin.xml","position":112,"original_position":112,"commit_id":"573e460a8ebb5ff674ff27d5e2ba0e37e9ee9a79","original_commit_id":"573e460a8ebb5ff674ff27d5e2ba0e37e9ee9a79","user":{"login":"jjohannes","id":1963746,"avatar_url":"https://avatars.githubusercontent.com/u/1963746?v=3","gravatar_id":"","url":"https://api.github.com/users/jjohannes","html_url":"https://github.com/jjohannes","followers_url":"https://api.github.com/users/jjohannes/followers","following_url":"https://api.github.com/users/jjohannes/following{/other_user}","gists_url":"https://api.github.com/users/jjohannes/gists{/gist_id}","starred_url":"https://api.github.com/users/jjohannes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jjohannes/subscriptions","organizations_url":"https://api.github.com/users/jjohannes/orgs","repos_url":"https://api.github.com/users/jjohannes/repos","events_url":"https://api.github.com/users/jjohannes/events{/privacy}","received_events_url":"https://api.github.com/users/jjohannes/received_events","type":"User","site_admin":false},"body":"`It's in general safer to assume...` ->\r\n`It is in general safer to assume...`","created_at":"2017-01-10T11:12:57Z","updated_at":"2017-01-10T11:32:54Z","html_url":"https://github.com/gradle/gradle/pull/1075#discussion_r95343495","pull_request_url":"https://api.github.com/repos/gradle/gradle/pulls/1075","_links":{"self":{"href":"https://api.github.com/repos/gradle/gradle/pulls/comments/95343495"},"html":{"href":"https://github.com/gradle/gradle/pull/1075#discussion_r95343495"},"pull_request":{"href":"https://api.github.com/repos/gradle/gradle/pulls/1075"}}},"pull_request":{"url":"https://api.github.com/repos/gradle/gradle/pulls/1075","id":99551816,"html_url":"https://github.com/gradle/gradle/pull/1075","diff_url":"https://github.com/gradle/gradle/pull/1075.diff","patch_url":"https://github.com/gradle/gradle/pull/1075.patch","issue_url":"https://api.github.com/repos/gradle/gradle/issues/1075","number":1075,"state":"open","locked":false,"title":"First elements of documentation of the Java Library plugin","user":{"login":"melix","id":316357,"avatar_url":"https://avatars.githubusercontent.com/u/316357?v=3","gravatar_id":"","url":"https://api.github.com/users/melix","html_url":"https://github.com/melix","followers_url":"https://api.github.com/users/melix/followers","following_url":"https://api.github.com/users/melix/following{/other_user}","gists_url":"https://api.github.com/users/melix/gists{/gist_id}","starred_url":"https://api.github.com/users/melix/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/melix/subscriptions","organizations_url":"https://api.github.com/users/melix/orgs","repos_url":"https://api.github.com/users/melix/repos","events_url":"https://api.github.com/users/melix/events{/privacy}","received_events_url":"https://api.github.com/users/melix/received_events","type":"User","site_admin":false},"body":"This pull request is about the documentation of the new Java library plugin. It needs to explain the new `api` and `implementation` configurations and how to use them properly, as well as explaining the consequences of the choice.","created_at":"2016-12-28T13:58:31Z","updated_at":"2017-01-10T11:32:54Z","closed_at":null,"merged_at":null,"merge_commit_sha":"24e29549bfc5dc605c9098e8f03e396f4e3da7db","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/gradle/gradle/pulls/1075/commits","review_comments_url":"https://api.github.com/repos/gradle/gradle/pulls/1075/comments","review_comment_url":"https://api.github.com/repos/gradle/gradle/pulls/comments{/number}","comments_url":"https://api.github.com/repos/gradle/gradle/issues/1075/comments","statuses_url":"https://api.github.com/repos/gradle/gradle/statuses/573e460a8ebb5ff674ff27d5e2ba0e37e9ee9a79","head":{"label":"gradle:cc-java-library-plugin-docs","ref":"cc-java-library-plugin-docs","sha":"573e460a8ebb5ff674ff27d5e2ba0e37e9ee9a79","user":{"login":"gradle","id":124156,"avatar_url":"https://avatars.githubusercontent.com/u/124156?v=3","gravatar_id":"","url":"https://api.github.com/users/gradle","html_url":"https://github.com/gradle","followers_url":"https://api.github.com/users/gradle/followers","following_url":"https://api.github.com/users/gradle/following{/other_user}","gists_url":"https://api.github.com/users/gradle/gists{/gist_id}","starred_url":"https://api.github.com/users/gradle/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gradle/subscriptions","organizations_url":"https://api.github.com/users/gradle/orgs","repos_url":"https://api.github.com/users/gradle/repos","events_url":"https://api.github.com/users/gradle/events{/privacy}","received_events_url":"https://api.github.com/users/gradle/received_events","type":"Organization","site_admin":false},"repo":{"id":302322,"name":"gradle","full_name":"gradle/gradle","owner":{"login":"gradle","id":124156,"avatar_url":"https://avatars.githubusercontent.com/u/124156?v=3","gravatar_id":"","url":"https://api.github.com/users/gradle","html_url":"https://github.com/gradle","followers_url":"https://api.github.com/users/gradle/followers","following_url":"https://api.github.com/users/gradle/following{/other_user}","gists_url":"https://api.github.com/users/gradle/gists{/gist_id}","starred_url":"https://api.github.com/users/gradle/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gradle/subscriptions","organizations_url":"https://api.github.com/users/gradle/orgs","repos_url":"https://api.github.com/users/gradle/repos","events_url":"https://api.github.com/users/gradle/events{/privacy}","received_events_url":"https://api.github.com/users/gradle/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gradle/gradle","description":"A powerful build system for the JVM","fork":false,"url":"https://api.github.com/repos/gradle/gradle","forks_url":"https://api.github.com/repos/gradle/gradle/forks","keys_url":"https://api.github.com/repos/gradle/gradle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gradle/gradle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gradle/gradle/teams","hooks_url":"https://api.github.com/repos/gradle/gradle/hooks","issue_events_url":"https://api.github.com/repos/gradle/gradle/issues/events{/number}","events_url":"https://api.github.com/repos/gradle/gradle/events","assignees_url":"https://api.github.com/repos/gradle/gradle/assignees{/user}","branches_url":"https://api.github.com/repos/gradle/gradle/branches{/branch}","tags_url":"https://api.github.com/repos/gradle/gradle/tags","blobs_url":"https://api.github.com/repos/gradle/gradle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gradle/gradle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gradle/gradle/git/refs{/sha}","trees_url":"https://api.github.com/repos/gradle/gradle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gradle/gradle/statuses/{sha}","languages_url":"https://api.github.com/repos/gradle/gradle/languages","stargazers_url":"https://api.github.com/repos/gradle/gradle/stargazers","contributors_url":"https://api.github.com/repos/gradle/gradle/contributors","subscribers_url":"https://api.github.com/repos/gradle/gradle/subscribers","subscription_url":"https://api.github.com/repos/gradle/gradle/subscription","commits_url":"https://api.github.com/repos/gradle/gradle/commits{/sha}","git_commits_url":"https://api.github.com/repos/gradle/gradle/git/commits{/sha}","comments_url":"https://api.github.com/repos/gradle/gradle/comments{/number}","issue_comment_url":"https://api.github.com/repos/gradle/gradle/issues/comments{/number}","contents_url":"https://api.github.com/repos/gradle/gradle/contents/{+path}","compare_url":"https://api.github.com/repos/gradle/gradle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gradle/gradle/merges","archive_url":"https://api.github.com/repos/gradle/gradle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gradle/gradle/downloads","issues_url":"https://api.github.com/repos/gradle/gradle/issues{/number}","pulls_url":"https://api.github.com/repos/gradle/gradle/pulls{/number}","milestones_url":"https://api.github.com/repos/gradle/gradle/milestones{/number}","notifications_url":"https://api.github.com/repos/gradle/gradle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gradle/gradle/labels{/name}","releases_url":"https://api.github.com/repos/gradle/gradle/releases{/id}","deployments_url":"https://api.github.com/repos/gradle/gradle/deployments","created_at":"2009-09-09T18:27:19Z","updated_at":"2017-01-10T03:31:13Z","pushed_at":"2017-01-10T11:12:10Z","git_url":"git://github.com/gradle/gradle.git","ssh_url":"git@github.com:gradle/gradle.git","clone_url":"https://github.com/gradle/gradle.git","svn_url":"https://github.com/gradle/gradle","homepage":"gradle.org","size":153240,"stargazers_count":4316,"watchers_count":4316,"language":"Java","has_issues":true,"has_downloads":false,"has_wiki":true,"has_pages":false,"forks_count":1616,"mirror_url":null,"open_issues_count":244,"forks":1616,"open_issues":244,"watchers":4316,"default_branch":"master"}},"base":{"label":"gradle:cc-java-library-plugin","ref":"cc-java-library-plugin","sha":"2e7c5b85a82b0236dc5ba0f572702618c4638718","user":{"login":"gradle","id":124156,"avatar_url":"https://avatars.githubusercontent.com/u/124156?v=3","gravatar_id":"","url":"https://api.github.com/users/gradle","html_url":"https://github.com/gradle","followers_url":"https://api.github.com/users/gradle/followers","following_url":"https://api.github.com/users/gradle/following{/other_user}","gists_url":"https://api.github.com/users/gradle/gists{/gist_id}","starred_url":"https://api.github.com/users/gradle/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gradle/subscriptions","organizations_url":"https://api.github.com/users/gradle/orgs","repos_url":"https://api.github.com/users/gradle/repos","events_url":"https://api.github.com/users/gradle/events{/privacy}","received_events_url":"https://api.github.com/users/gradle/received_events","type":"Organization","site_admin":false},"repo":{"id":302322,"name":"gradle","full_name":"gradle/gradle","owner":{"login":"gradle","id":124156,"avatar_url":"https://avatars.githubusercontent.com/u/124156?v=3","gravatar_id":"","url":"https://api.github.com/users/gradle","html_url":"https://github.com/gradle","followers_url":"https://api.github.com/users/gradle/followers","following_url":"https://api.github.com/users/gradle/following{/other_user}","gists_url":"https://api.github.com/users/gradle/gists{/gist_id}","starred_url":"https://api.github.com/users/gradle/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gradle/subscriptions","organizations_url":"https://api.github.com/users/gradle/orgs","repos_url":"https://api.github.com/users/gradle/repos","events_url":"https://api.github.com/users/gradle/events{/privacy}","received_events_url":"https://api.github.com/users/gradle/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gradle/gradle","description":"A powerful build system for the JVM","fork":false,"url":"https://api.github.com/repos/gradle/gradle","forks_url":"https://api.github.com/repos/gradle/gradle/forks","keys_url":"https://api.github.com/repos/gradle/gradle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gradle/gradle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gradle/gradle/teams","hooks_url":"https://api.github.com/repos/gradle/gradle/hooks","issue_events_url":"https://api.github.com/repos/gradle/gradle/issues/events{/number}","events_url":"https://api.github.com/repos/gradle/gradle/events","assignees_url":"https://api.github.com/repos/gradle/gradle/assignees{/user}","branches_url":"https://api.github.com/repos/gradle/gradle/branches{/branch}","tags_url":"https://api.github.com/repos/gradle/gradle/tags","blobs_url":"https://api.github.com/repos/gradle/gradle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gradle/gradle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gradle/gradle/git/refs{/sha}","trees_url":"https://api.github.com/repos/gradle/gradle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gradle/gradle/statuses/{sha}","languages_url":"https://api.github.com/repos/gradle/gradle/languages","stargazers_url":"https://api.github.com/repos/gradle/gradle/stargazers","contributors_url":"https://api.github.com/repos/gradle/gradle/contributors","subscribers_url":"https://api.github.com/repos/gradle/gradle/subscribers","subscription_url":"https://api.github.com/repos/gradle/gradle/subscription","commits_url":"https://api.github.com/repos/gradle/gradle/commits{/sha}","git_commits_url":"https://api.github.com/repos/gradle/gradle/git/commits{/sha}","comments_url":"https://api.github.com/repos/gradle/gradle/comments{/number}","issue_comment_url":"https://api.github.com/repos/gradle/gradle/issues/comments{/number}","contents_url":"https://api.github.com/repos/gradle/gradle/contents/{+path}","compare_url":"https://api.github.com/repos/gradle/gradle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gradle/gradle/merges","archive_url":"https://api.github.com/repos/gradle/gradle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gradle/gradle/downloads","issues_url":"https://api.github.com/repos/gradle/gradle/issues{/number}","pulls_url":"https://api.github.com/repos/gradle/gradle/pulls{/number}","milestones_url":"https://api.github.com/repos/gradle/gradle/milestones{/number}","notifications_url":"https://api.github.com/repos/gradle/gradle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gradle/gradle/labels{/name}","releases_url":"https://api.github.com/repos/gradle/gradle/releases{/id}","deployments_url":"https://api.github.com/repos/gradle/gradle/deployments","created_at":"2009-09-09T18:27:19Z","updated_at":"2017-01-10T03:31:13Z","pushed_at":"2017-01-10T11:12:10Z","git_url":"git://github.com/gradle/gradle.git","ssh_url":"git@github.com:gradle/gradle.git","clone_url":"https://github.com/gradle/gradle.git","svn_url":"https://github.com/gradle/gradle","homepage":"gradle.org","size":153240,"stargazers_count":4316,"watchers_count":4316,"language":"Java","has_issues":true,"has_downloads":false,"has_wiki":true,"has_pages":false,"forks_count":1616,"mirror_url":null,"open_issues_count":244,"forks":1616,"open_issues":244,"watchers":4316,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/gradle/gradle/pulls/1075"},"html":{"href":"https://github.com/gradle/gradle/pull/1075"},"issue":{"href":"https://api.github.com/repos/gradle/gradle/issues/1075"},"comments":{"href":"https://api.github.com/repos/gradle/gradle/issues/1075/comments"},"review_comments":{"href":"https://api.github.com/repos/gradle/gradle/pulls/1075/comments"},"review_comment":{"href":"https://api.github.com/repos/gradle/gradle/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/gradle/gradle/pulls/1075/commits"},"statuses":{"href":"https://api.github.com/repos/gradle/gradle/statuses/573e460a8ebb5ff674ff27d5e2ba0e37e9ee9a79"}}}}
{"actor":{"display_login":"jjohannes"}}