{"id":21278,"date":"2014-02-18T10:00:27","date_gmt":"2014-02-18T08:00:27","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=21278"},"modified":"2014-02-18T08:12:30","modified_gmt":"2014-02-18T06:12:30","slug":"creating-maven-source-and-javadoc-artifacts","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2014\/02\/creating-maven-source-and-javadoc-artifacts.html","title":{"rendered":"Creating Maven Source and Javadoc Artifacts"},"content":{"rendered":"

Many people are aware of maven source and javadoc artifacts but don\u2019t know why they would want to create them. I was definitely in this camp \u2013 I can see why people want this information but it seemed like a relatively inefficient way to get it since it requires manual navigation of the maven repository.<\/p>\n

Then I got hit by a clue stick.<\/p>\n

These artifacts are used by IDEs, not people. If you\u2019re using maven dependencies the IDE is smart enough to know how to find these artifacts. The source artifact is used when you\u2019re single-stepping through code in the debugger \u2013 you no longer have to explicitly bind source code to libraries in the IDE. The javadoc artifact is used for auto-completion and context-sensitive help in the editor.<\/p>\n

Neither of these is required \u2013 I was happy using \u2018vi\u2019 for many years \u2013 but it definitely improves your productivity when you mostly know what you need but aren\u2019t quite sure of the details.<\/p>\n

Source Artifacts<\/h2>\n

The source artifacts are the easiest to create. Add a plugin that will be run automatically as part of a standard build and you\u2019re done. Builds take slightly longer but it\u2019s probably not enough to worry about since you\u2019re just creating an archive of a few directories.<\/p>\n

<project xmlns=\"http:\/\/maven.apache.org\/POM\/4.0.0\" xmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\"\r\n    xsi:schemaLocation=\"http:\/\/maven.apache.org\/POM\/4.0.0 http:\/\/maven.apache.org\/xsd\/maven-4.0.0.xsd\">\r\n    <build>\r\n        <plugins>\r\n            <!-- create source jar -->\r\n            <plugin>\r\n                <groupId>org.apache.maven.plugins<\/groupId>\r\n                <artifactId>maven-source-plugin<\/artifactId>\r\n                <version>2.1.1<\/version>\r\n                <executions>\r\n                    <execution>\r\n                        <id>attach-sources<\/id>\r\n                        <phase>verify<\/phase>\r\n                        <goals>\r\n                            <!-- produce source artifact for project main sources -->\r\n                            <goal>jar-no-fork<\/goal>\r\n                            <!-- produce test source artifact for project test sources -->\r\n                            <goal>test-jar-no-fork<\/goal>\r\n                        <\/goals>\r\n                    <\/execution>\r\n                <\/executions>\r\n            <\/plugin>\r\n        <\/plugins>\r\n    <\/build>\r\n<\/project><\/pre>\n
Javadoc Artifacts<\/h2>\n
Javadoc artifacts are a little more complex since you\u2019ll probably want to create a human-friendly site at the same time. The biggest issue there, in my experience, is that external classes were opaque since it took so much effort to create the necessary links. The maven plugin now takes care of that for us!<\/p>\n
This artifact takes a significant amount of time to build so you probably don\u2019t want to do it every time. There are two approaches \u2013 either specify the maven target explicitly or tie it to a custom profile, e.g., \u2018javadoc\u2019. The configuration below uses a custom profile.
 
<\/div> <\/div><\/p>\n
<project xmlns=\"http:\/\/maven.apache.org\/POM\/4.0.0\" xmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\"\r\n    xsi:schemaLocation=\"http:\/\/maven.apache.org\/POM\/4.0.0 http:\/\/maven.apache.org\/xsd\/maven-4.0.0.xsd\">\r\n\r\n        <profiles>\r\n            <!-- create javadoc -->\r\n            <profile>\r\n                <id>javadoc<\/id>\r\n                <build>\r\n                    <plugins>\r\n                        <plugin>\r\n                            <groupId>org.apache.maven.plugins<\/groupId>\r\n                        <artifactId>maven-javadoc-plugin<\/artifactId>\r\n                        <version>2.9.1<\/version>\r\n                        <configuration>\r\n                            <detectLinks \/>\r\n                            <includeDependencySources>true<\/includeDependencySources>\r\n                            <dependencySourceIncludes>\r\n                                <dependencySourceInclude>com.invariantproperties.project.student:*<\/dependencySourceInclude>\r\n                            <\/dependencySourceIncludes>\r\n                            <!-- heavily used dependencies -->\r\n                            <links>\r\n                                <link>http:\/\/docs.oracle.com\/javase\/7\/docs\/api\/<\/link>\r\n                                <link>http:\/\/docs.oracle.com\/javaee\/6\/api<\/link>\r\n                                <link>http:\/\/docs.spring.io\/spring\/docs\/current\/javadoc-api\/<\/link>\r\n                                <link>http:\/\/docs.spring.io\/spring-data\/commons\/docs\/1.6.2.RELEASE\/api\/<\/link>\r\n                                <link>http:\/\/docs.spring.io\/spring-data\/jpa\/docs\/1.4.3.RELEASE\/api\/<\/link>\r\n                                <link>http:\/\/docs.spring.io\/spring-data\/data-jpa\/docs\/1.4.3.RELEASE\/api\/<\/link>\r\n                                <link>https:\/\/jersey.java.net\/apidocs\/1.17\/jersey\/<\/link>\r\n                                <link>http:\/\/hamcrest.org\/JavaHamcrest\/javadoc\/1.3\/<\/link>\r\n                                <link>http:\/\/eclipse.org\/aspectj\/doc\/released\/runtime-api\/<\/link>\r\n                                <link>http:\/\/eclipse.org\/aspectj\/doc\/released\/weaver-api<\/link>\r\n                                <link>http:\/\/tapestry.apache.org\/5.3.7\/apidocs\/<\/link>\r\n                            <\/links>\r\n                        <\/configuration>\r\n                        <executions>\r\n                            <execution>\r\n                                <id>aggregate<\/id>\r\n                                <!-- <phase>site<\/phase> -->\r\n                                <phase>package<\/phase>\r\n                                <goals>\r\n                                    <goal>aggregate<\/goal>\r\n                                    <goal>jar<\/goal>\r\n                                <\/goals>\r\n                            <\/execution>\r\n                        <\/executions>\r\n                    <\/plugin>\r\n                <\/plugins>\r\n            <\/build>\r\n\r\n            <reporting>\r\n                <plugins>\r\n                    <plugin>\r\n                        <groupId>org.apache.maven.plugins<\/groupId>\r\n                        <artifactId>maven-javadoc-plugin<\/artifactId>\r\n                        <version>2.9.1<\/version>\r\n                        <configuration>\r\n                            <!-- Default configuration for all reports -->\r\n                        <\/configuration>\r\n                        <reportSets>\r\n                            <reportSet>\r\n                                <id>non-aggregate<\/id>\r\n                                <configuration>\r\n                                    <!-- Specific configuration for the non aggregate report -->\r\n                                <\/configuration>\r\n                                <reports>\r\n                                    <report>javadoc<\/report>\r\n                                <\/reports>\r\n                            <\/reportSet>\r\n                            <reportSet>\r\n                                <id>aggregate<\/id>\r\n                                <configuration>\r\n                                    <!-- Specific configuration for the aggregate report -->\r\n                                <\/configuration>\r\n                                <reports>\r\n                                    <report>aggregate<\/report>\r\n                                <\/reports>\r\n                            <\/reportSet>\r\n                        <\/reportSets>\r\n                    <\/plugin>\r\n                <\/plugins>\r\n            <\/reporting>\r\n        <\/profile>\r\n    <\/profiles>\r\n<\/project><\/pre>\n
package-info.java<\/h2>\n
Finally each package should have a package-info.java<\/b> file. This replaces the old package-info.html file but is an improvement since it allows the use of class annotations. (It will not be compiled since it\u2019s an invalid class name.)<\/p>\n
I\u2019ve found it extremely helpful to include links to resources that help me understand why the classes look the way they do. For instance the metadata package in my \u2018student\u2019 project contains links to my blog posts, other blog posts that I\u2019ve found useful, and even the appropriate Oracle tutorial. At a company these could be links to wiki pages.<\/p>\n
\/**                     \r\n * Classes that support JPA Criteria Queries for persistent entities.\r\n *                          \r\n * @see <a href=\"http:\/\/invariantproperties.com\/2013\/12\/19\/project-student-persistence-with-spring-data\/\">Project Student: Persistence with Spring Data<\/a>\r\n * @see <a href=\"http:\/\/invariantproperties.com\/2013\/12\/29\/project-student-jpa-criteria-queries\/\">Project Student: JPA Criteria Queries<\/a>\r\n * @see <a href=\"http:\/\/www.petrikainulainen.net\/programming\/spring-framework\/spring-data-jpa-tutorial-part-four-jpa-criteria-queries\/\">Spring Data JPA Tutorial Part Four: JPA Criteria Queries<\/a> [www.petrikainulainen.net]\r\n * @see <a href=\"http:\/\/docs.oracle.com\/javaee\/6\/tutorial\/doc\/gjitv.html\">JEE Tutorial<\/a>      \r\n *  \r\n * @author Bear Giles <bgiles@coyotesong.com>\r\n *\/             \r\npackage com.invariantproperties.project.student.metamodel;<\/pre>\n
Source Code<\/h2>\n