Tag: maven

You have developed some crafty Java library or Maven plugin and now you want to distribute it to other users through Maven Central repository? Using Sonatype Open Source Software Repository Hosting Service is a nice way for open source projects to achieve that and there’s two options to get your artifacts in it: 1. Release with Sonatype’s process or 2. Use Bintray’s process. In short, both options end up with the same results, your project’s artifacts are in Maven Central repository, but using Sonatype’s process and Maven release plugin makes it easy to release new version after you have set it up.

The process with Sonatype has a bit more steps than Bintray but if you follow the user guide, quite easy. And now as they have made some changes to their release process it’s easier more or less the same than using Bintray. All you need to do is to sign up a Sonatype JIRA account, create a JIRA ticket and make some POM/settings configuration and then use Maven release plugin to perform release. The procedure is described in Sonatype OSS Maven Repository Usage Guide but here is a short recap.

Performing release deployment with the Maven release plugin

Using Maven to perform release deployment to OSSRH is described in Sonatype’s guide which tells you how to do it manually or through the Maven release plugin which I find convenient.

First start with Initial Setup and create your JIRA account and new project ticket. The new project ticket triggers creation of your repositories. While your repositories are taken care of you should review the requirements for components in Central.

The artifacts need to be GPG signed so if you yet haven’t got a GPG key follow this guide to create one. Then you need to have your GPG key in a keyserver so start by sending your GPG key to keyserver:

gpg --keyserver pool.sks-keyservers.net --send-keys <your KEYID>

gpg --keyserver pool.sks-keyservers.net --send-keys <your KEYID>

If you have more than one GPG key in your keychain then it’s useful to set a default key to be used for signing. Edit your ~/.gnupg/gpg.conf and uncomment the “default-key KEYID” line and add your KEYID.

The configuration for the Maven release plugin should include disabling the release profile that is part of the Maven Super POM, since we are using our own profile, and specify the deploy goal together with the activation of our release profile

You can see the full pom.xml e.g from my markdown-page-generator-plugin’s pom.xml.

Publishing Snapshots

Snapshot deployment are performed when your version ends in -SNAPSHOT. You do not need to fulfil the requirements when performing snapshot deployments and can simply run

$ mvn clean deploy

$ mvn clean deploy

Successfully deployed SNAPSHOT versions will be found in Snapshot repository. If you need to delete your artifacts, you can log in to Sonatype’s Nexus using the same credentials you use to access to the Sonatype JIRA.

Performing a Release Deployment

The Maven Release Plugin can be used to automate the changes to the Maven POM files, sanity checks, the SCM operations required, the actual deployment execution and you can perform a release deployment to OSSRH with the following steps.

Prepare the release by answering the prompts for versions and tags

$ mvn release:clean release:prepare

$ mvn release:clean release:prepare

If prepare fails use

$ mvn release:rollback
$ mvn release:clean

$ mvn release:rollback
$ mvn release:clean

The prepare will create a new tag in SCM, even in GitHub, automatically checking in on your behalf. For it to work you need to have working public key in GitHub for git-push.

Perform the release. The perform process will ask for your gpg.passphrase if you don’t give it with passphrase argument.

$ mvn release:perform

$ mvn release:perform

For some reason I can’t provide the GPG passphrase when Maven GPG plugin asks it and I have to use the -Dgpg.passphrase argument.

If release:perform fails to error “gpg: signing failed: No pinentry” then on macOS you need to restart gpg-agent and define pinentry-program. gnupg21 comes with pineentry as dependency. Or see Gist about commit signing with GPG on macOS.

The first time you promote a release, you need to comment on the OSSRH JIRA ticket you created so OSSRH can know you are ready to be synced.

Manually Releasing the Deployment to the Central Repository

If you don’t want to release artifacts automatically you can also do it manually. Set the autoReleaseAfterClose set to false so you can inspect and potentially release the deployed artifacts manually. Then to release your artifacts is done through Nexus as described in the guide.

I found out about Bintray after I had already used the Sonatype’s way to release artifacts so I haven’t tested this myself. Bintray’s process is more or less similar than Sonatype’s but if I hadn’t read the blog post about how to do it I wouldn’t have know where to start. In short the process is the following.

Register to Bintray and set up auto-signing: Generate yourself a keypair, if you don’t have one. Add it to your profile, and setup your default Maven repo (or a new one) for signing with your GPG key: Bintray can then sign your jars automatically.

Add your Sonatype account under “accounts”. If you don’t have one, follow this procedure

Create and link your package: Import from a GitHub repo or create a new package for your Maven project.

Summary

For distributing your open source projects’ artifacts through Maven Central repository and OSSRH you have two options: 1. Release with Sonatype’s process or 2. Use Bintray’s process. Both options end up with the same results: your project’s artifacts are in Maven Central repository. In my opinion if you’re using Maven then it doesn’t really matter which option you choose.

Before Sonatype simplified their process for making releases to OSSRH the Bintray’s process was the only almost pain-free gateway to Maven Central. But with the new Sonatype way the two alternative ways are more or less the same and I could say that Sonatype’s new process feels a bit easier when using the Maven release plugin. In practice there’s not much differences, e.g. both supports SNAPSHOTs, Sonatype in OSSRH and Bintray in oss.jfrog.org. Bintray is more flexible especially if not using Maven so if you’re using other tools like Gradle then it’s the easier way to go.

Using the WebLogic 12c 12.1.2 Maven plug-In for deployment is much easier and quicker than going through the WebLogic Server’s AdminServer and Oracle Documentation provides good examples how to do it. The weblogic-maven-plugin provides enhanced functionality to install, start and stop servers, create domains, execute WLST scripts, and compile and deploy applications.

The weblogic-maven-plugin plug-in is provided as a pre-built JAR file and accompanying pom file. In short, installing and configuring the WebLogic 12c Maven sync plug-in contains following steps:

And you’re ready to deploy with Maven. A lot more easier than generating the WebLogic 11g R2 Maven Plug-in where you had to i.a. build the jar by yourself.

The Maven plug-in can be used e.g. from application’s POM file and be bound to some phase of the Maven life cycle. For example it can be bound to “install” phase and every time you run the “mvn install” command, the deployment plug-in is also called. In my opinion better way to use the plug-in is to add it as a profile so you can call it just when you want with command like “mvn clean install -Pdeploy-wls“.

The user credentials in the POM file are provided as clear-text but for more security you can use secure configuration authentication mechanism which stores the user name and password in encrypted form in an external file, and then uses it to supply the user credentials with which to connect to the WebLogic Server domain, along with the key that was used to encrypt the file.

Generating documents is always not the most pleasant job but it can be made easier by using easier markup language like Markdown. For that purpose I made last year a simple Markdown to HTML Page Generator Maven Plugin and now it’s also available in Maven Central.

“Markdown to HTML Page Generator” is a simple Maven Plugin which reads the input directory for Markdown files with .md suffix and outputs HTML files to target directory. There are couple of configuration options to set the input/output directories and if you want to add header and footer files to make it structurally valid HTML. The plugin uses pegdown Markdown processor.

Maven plugin artifacts can be found in Sonatypes’ OSS Maven repository:

Writing documentation or user guide isn’t the most interesting part of the software project but it’s still needed to be done and important for the end users. There are many ways to achieve documentation but using Markdown is good way to make it easier. After that you just need to convert it to HTML and as I couldn’t find a suitable Maven plugin to do that nicely I wrote one myself: markdown-page-generator-plugin.

Software developers are a bit lazy to write good and up to date documentation and as I needed to write the API documentation for the web application as separate HTML pages I got to know the issue first hand. I like writing documents but typing the API documentation as static HTML wasn’t very effective or fun. Fortunately it was quite easy to do it with Markdown which allows you to write documentation using an easy-to-read, easy-to-write plain text format which you can then convert to HTML. After that the only problem was to enable easy HTML generation directly from Maven Lifecycle and thus was the “Markdown to HTML Page Generator Maven Plugin” developed.

Markdown to HTML Page Generator Maven Plugin

“Markdown to HTML Page Generator” is a simple Maven Plugin which reads the input directory for Markdown files with .md suffix and outputs HTML files to target directory. There are couple of configuration options to set the input/output directories and if you want to add header and footer files to make it structurally valid HTML. The plugin uses pegdown Markdown processor.

Source code

Usage

Using the plugin could be easier but as it isn’t in Maven repository you have to e.g. add it as Maven project to same Eclipse workspace as your project and build it. After that add it as a plugin to your build and it’s run automatically when processing sources. You can also run it from command line with “mvn com.ruleoftech:markdown-page-generator-plugin:generate”.

The Maven plug-in can be used e.g. from application’s POM file and be bound to some phase of the Maven life cycle. For example it can be bound to “install” phase and every time you run the “mvn install” command, the deployment plug-in is also called. In my opinion better way to use the plug-in is to add it as a profile so you can call it just when you want with command like “mvn clean install -Pdeploy-wls”.

The user credentials in the POM file are provided as clear-text but for more security you can use secure configuration authentication mechanism which stores the user name and password in encrypted form in an external file, and then uses it to supply the user credentials with which to connect to the WebLogic Server domain, along with the key that was used to encrypt the file.

Eclipse 3.7 Indigo has integrated Maven m2e plugin but is missing some expected functionality which was previously present in Sonatype releases by default. If you want your Maven Console to show something you must also install the optional “m2e – slf4j over logback logging” plugin.

When installing the m2e plugin there is an optional feature “m2e – slf4j over logback logging” which is needed for the Maven Console to work. Without it the plugin produces no output to Eclipse’s Maven Console view so that it is impossible to track plugin’s activity (background maven builds, source and javadoc downloads, etc).

There is a bug filed about it but it is resolved with comment “As a tool, m2e is not in the position to impose any specific slf4j logging backend on the host Eclipse installation.” That seems kinda strange as without the optional component the plugin is missing useful parts.