• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Devaka Cooray
  • Knute Snortum
  • Paul Clapham
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • Jeanne Boyarsky
  • Bear Bibeault
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Ron McLeod
  • Piet Souris
  • Frits Walraven
Bartenders:
  • Ganesh Patekar
  • Tim Holloway
  • salvin francis

Need example projects using Maven on github  RSS feed

 
Ranch Hand
Posts: 87
7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I am looking for a few good examples of Java projects using Maven on github. Does anyone have recommendations?

I have a github-resident project that provides a library for building triangulated meshes (Delaunay Triangulations), analyzing airborne Lidar, and performing a few other computational-geometry functions (see  The Tinfour Project).  I think I did an okay job on the algorithm and coding aspects of the project, but I made some mistakes in terms of project organization and build utilities when I first set it up.

Anyway, I am currently working on refactoring the project to use Maven and eventually hope to post my libraries to a public repository. I've spent a good deal of time looking at documentation and thinking about the best way to organize things.  Every so often, I stumble across some aspect of the project that seems a bit fuzzy.   So I am hoping to find examples of projects that have proper treatments for organization and build issues.

For instance, right now I'm trying to figure out the best way to set up my Javadoc (into which I've put a lot of time).  I've been looking through the web, but the discussions I've found don't seem to relate well to working with github. Seeing a example of somebody who correctly implements the Maven conventions would really help.

In general, I'd like to see a project or two that
  • Isn't too big
  • Has good Javadoc
  • Builds multiple Jar files (multiple modules)
  • Doesn't do anything too customized (sticks to standard approaches)
  • Has a small but non-zero number of external dependencies


  • Thanks in advance for your help,

    Gary
     
    Saloon Keeper
    Posts: 10209
    216
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    You could take a look at my Game of Life project on GitHub: https://github.com/Nibsi/Evolution

    It was mostly a playground for me to practice writing documentation and it's unfinished and not actively being worked on, but it might give you an idea.

    It's divided in three submodules: the core Game of Life library, a generations module that provides different implementations of the Game of Life, and a swing module that allows user interaction through a Swing interface.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stephan,

    Thanks.  I'll take a look.

    I figure that if I can find three or four different projects, they'll pretty much cover all the variations.

    Gary
     
    Stephan van Hulst
    Saloon Keeper
    Posts: 10209
    216
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    You might also want to check out my Advent of Code project, but it's a bit more complex, undocumented and I'm about to overhaul it. https://github.com/Nibsi/Advent-of-Code

    It has sub-sub-modules though! It also shows how I have an "executable" module that just acts to fire up the user interface and to put runtime dependencies on the class path.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stephan,

    Thanks again for the suggestion.  I've picked up a couple of important nuances from your examples. For instance, I'm using macro's such as plugin.version through the tree.

    A question.  Following an example in the Apache Maven "getting started" page, I used a maven artifact to automatically generate an example pom.  When I did, it included a substantial number of entries under "pluginManagement".  The generated pom,xml includes the comment "lock down plugins versions to avoid using Maven defaults".  But it adds a lot of ugly clutter to the pom and, having looked at a bunch of pom.xml files in various projects,  it seems to me that most developers leave that out.  I also see that you don't use it in your own "Evolution" pom.  Is it a good idea to include the plugin version specifications?  I'd prefer to leave it out because the extra specifications degrade the signal-to-noise ratio of the specification in terms of a human trying to understand the structure of the pom...  though if it's necessary as a coding practice, that would be more important than readability.
     
    Stephan van Hulst
    Saloon Keeper
    Posts: 10209
    216
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    The idea is that after you've created a project and committed it to a source repository, another person can just check it out and rebuild it without problems. If you don't explicitly state the version numbers for the plugins you use to build your project, Maven will use whatever is the default for the Maven version on the system that is building the project.

    It's really up to you. If you want to lock the plugin versions to whatever you used to build your project, you can do that. If you just want to assume that newer versions of Maven will build your project just fine, you can leave out the clutter.

    You might want to consider documenting in your POM the latest version of Maven that you used to successfully build the project. That way anyone who wants to build the project doesn't have to go on a wild goose chase if it doesn't build right away.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stephan,

    Thanks again.   I will follow your advice add a comment to my pom.xml indicating the version of maven I use.


    I've tried to keep my project organization simple and non-innovative as possible, so hopefully maven versions will never be a problem.

     
    Bartender
    Posts: 20724
    124
    Android Eclipse IDE Java Linux Redhat Tomcat Server
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    A properly-designed Maven project is one that you can do a "mvn clean", ZIP up the POM directory and its children, send the ZIP file to the other side of the Earth and the person there will be able to build an identical and functioning copy of the project with nothing more pre-installed on their computer than a compatible Java compiler and copy of Maven. In the case where you have dependent projects, it's a bit more complex than that, but not much.

    You SHOULD include version constraints on your dependencies and plugins on the POM. Failure to do so can not merely cause the copy of the project you shipped out to fail to build properly, but also can eventually cause your own copy of the project to build. Good version constraints should be either for one specific version or for a tested and confirmed range, never open-ended, even "version X or later". Sometimes "later" breaks things even though Java tries to be backwards compatible.

    I do recommend a good README.md file be part of the project directory and that can (probably should) indicate what versions of JDK and Maven you worked with. Maven is generally pretty compatible between minor releases, only major ones usually break things in a build as long as you're not getting too friendly with obscure build features.

    For many projects, you can simply post the POM directory to github, although for complex projects where for example you might want to publish both Maven project files and a directory full of external documentation, a higher-level directory containing both would be appropriate.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks again to the forum members who provided answers and useful advice to my original post.  My open-source project has now completed the initial transition to a Maven build environment.   I've also posted compiled Jar files on the Maven Central Repository.

    Anyone would look like to see how it turned out, may do so by looking at https://github.com/gwlucastrig/Tinfour

    I've got to say that there was a lot of learning curve on this.  And I steadfastly hope nobody tries to use my project as an example when doing their own work...  

    If anyone spots something that needs fixing or improvement, I welcome your suggestions.

    Gary


     
    Tim Holloway
    Bartender
    Posts: 20724
    124
    Android Eclipse IDE Java Linux Redhat Tomcat Server
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Most impressive!
     
    Stephan van Hulst
    Saloon Keeper
    Posts: 10209
    216
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
  • All your POMs are poorly indented. Use consistent indenting.
  • It's common for group and artifact IDs to be all lowercase.
  • Your parent POM doesn't lock down the following plugins: maven-antrun-plugin, maven-assembly-plugin, maven-dependency-plugin, maven-release-plugin.
  • Your parent POM declares dependencies that should be declared in sub-modules. Right now it forces all sub-modules to have dependencies they might not need. Use <dependencyManagement> if you just want to configure dependencies without requiring them.
  • You can remove <packaging>jar</packaging> from your POMs, because that's the default.
  • Try to list plugins and dependencies alphabetically by group ID and then by artifact ID, to make them easy to locate.
  • Properties are inherited, so you don't have to declare the source encoding and compiler version in every sub-module.
  • Plugin configuration is inherited, so you don't have to reconfigure plugins in sub-modules when you've configured them in the <pluginManagement> element of the parent POM.
  • You can pre-configure the versions of commonly used plugins in your parent POM. Your sub-modules then only have to declare the group and artifact IDs, and can omit the version.
  • Eliminate explicit declarations of transitive dependencies from your POM. For instance, your analysis module directly depends on commons-math3, but the declaration is unnecessary because it already gets that dependency through the core module.

  • I created a Pull Request that merges these changes into your repository. Let me know what you think.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stephan,

    Thanks for the assessment and for taking the time to put together a Pull Request.  I will look at it this weekend.    I spent a lot of time looking at the documentation, but I came away with the feeling that there are fundamental Maven use patterns  that I am just not seeing.  So your updated POMs are especially welcome.  

    You caught one issue in particular that concerns me. The core module is not supposed to have dependencies on anything except the standard Java API.  I'll have to figure out how the commons-math3 dependency  got in there.

    Gary
     
    Tim Holloway
    Bartender
    Posts: 20724
    124
    Android Eclipse IDE Java Linux Redhat Tomcat Server
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Well, the documentation looks pretty, at any rate!

    I'd amend Stephan's suggestions just slightly.

    First, in a complex project, I find nothing wrong with including the <packaging>jar</packaging> in your POMs. It may be the default, but even defaults serve as documentation. It points out that this POM isn't a WAR explicitly instead of implicitly.

    Second, in the case of transitive dependencies, that's something to take with a grain of salt. Sometimes a higher-level module might have very specific dependency requirements, in which case, allowing the dependency to slide in under a possibly unacceptable version would be undesirable. In such a case, you'd want the explicit dependency. Although once you get into that, you've embarked on the Maven equivalent of "DLL Hell", where changing a version one place can result in a lot of work bringing other places into agreement. Not that having fully transitive dependencies will save you if you're also pulling in third-party libraries.
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks Tim!

    Recognizing that the Tinfour project has a relatively narrow user base, I tried to provide enough information to make it accessible to those developers who would be interested in using it.

    When you refer to "pretty" documentation,  I take it you saw the project wiki pages?  Since Triangulated Irregular Networks (TINs) are kind of a specialized topic, I felt it would help potential developers if I provided background information on some of the theory and applications. So I've started posting wiki pages.  Some of them are better than others, but my favorite would have to be the one on Robin Sibson's Natural Neighbor Interpolation algorithm.  I think that Natural Neighbors is one of the most under-appreciated interpolation techniques out there.  Sibson died just a couple of years ago, so I have no idea what he would have thought of my work.  But I think that anything I can do to make the Natural Neighbors technique more available to potential applications is effort well spent.  
     
    Gary W. Lucas
    Ranch Hand
    Posts: 87
    7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stephan,

    Thank you again for the insights your provided about Maven.  You helped clarify a number of issues that had confused me.

    Gary
     
    It is sorta covered in the JavaRanch Style Guide.
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!