Merge pull request #82 from cyberark/6-maven-central-publishing

6 Support for Maven Central Publishing

Author: sgnn7

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [3.0.0] - 2020-06-22
 ### Fixed
 - Encode spaces to "%20" instead of "+". This encoding fixes an issue where Conjur
   variables that have spaces were not encoded correctly
@@ -17,6 +19,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   code
 - README has been updated with example SSLContext setup and it's use in Conjur
   class constructors
+- Introduced [upgrade instructions](https://github.com/cyberark/conjur-api-java/UPGRADING.md) to provide instructions for
+  upgrading to 3.0.0, or make use of published artifacts. These can be found in
+  `UPGRADING.md`. ([cyberark/conjur-api-java#77](https://github.com/cyberark/conjur-api-java/issues/77))
+
+### Changed
+- Revised package references from `net.conjur.api` to `com.cyberark.conjur.api` 
+  ([cyberark/conjur-api-java#6](https://github.com/cyberark/conjur-api-java/issues/6))
 
 ## [2.2.1] - 2020-05-08
 ### Fixed
@@ -55,7 +64,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Authn tokens now use the new Conjur 5 format - [PR #21](https://github.com/cyberark/conjur-api-java/pull/21)
 - Configuration change. When using environment variables, use `CONJUR_AUTHN_LOGIN` and `CONJUR_AUTHN_API_KEY` now instead of `CONJUR_CREDENTIALS` - https://github.com/cyberark/conjur-api-java/commit/60344308fc48cb5380c626e612b91e1e720c03fb
 
-[Unreleased]: https://github.com/cyberark/conjur-api-java/compare/v2.2.1...HEAD
+[Unreleased]: https://github.com/cyberark/conjur-api-java/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/cyberark/conjur-api-java/compare/v2.2.1...v3.0.0
 [2.0.0]: https://github.com/cyberark/conjur-api-java/compare/v1.1.0...v2.0.0
 [2.1.0]: https://github.com/cyberark/conjur-api-java/compare/v2.0.0...v2.1.0
 [2.2.0]: https://github.com/cyberark/conjur-api-java/compare/v2.1.0...v2.2.0

Jenkinsfile

@@ -20,7 +20,7 @@ pipeline {
         }
       }
     }
-    
+
     stage('Create and archive the Maven package') {
       steps {
         sh './bin/build.sh'
@@ -37,12 +37,21 @@ pipeline {
       }
     }
 
-    stage('Publish the Maven package') {
+    stage('Perform Snapshot Deployment') {
       when {
         branch 'master'
       }
       steps {
-        echo 'TODO'
+        sh 'summon ./bin/deploy-snapshot.sh'
+      }
+    }
+
+    stage('Perform Release Deployment') {
+      when {
+        buildingTag()
+      }
+      steps {
+        sh 'summon ./bin/deploy-release.sh'
       }
     }
   }

README.md

@@ -42,7 +42,7 @@ To do so from the source using Maven, following the setup steps below:
 
 ```xml
     <dependency>
-      <groupId>net.conjur.api</groupId>
+      <groupId>com.cyberark.conjur.api</groupId>
       <artifactId>conjur-api</artifactId>
       <version>2.2.0</version>
     <dependency>
@@ -95,12 +95,76 @@ our [Contributing](https://github.com/cyberark/conjur-api-java/blob/master/CONTR
     or
     ```sh-session
     $ mvn install:install-file -Dfile=/path/to/api/repo/target/conjur-api-$VERSION-with-dependencies.jar \
-        -DgroupId=net.conjur.api \
+        -DgroupId=com.cyberark.conjur.api \
         -DartifactId=conjur-api \
         -Dversion=$VERSION \
         -Dpackaging=jar
     ```
 
+### Using Maven Releases
+
+To make use of tagged releases published to Maven, verify that you have the dependency 
+added to your `pom.xml`
+
+1. Add the following snippet to `pom.xml`
+```xml
+<dependency>
+  <groupId>com.cyberark.conjur.api</groupId>
+  <artifactId>conjur-java-api</artifactId>
+  <version>x.x.x</version>
+</dependency>
+```
+
+### Using Maven Snapshots
+To make use of SNAPSHOTS, which are deployed following a nightly build, there are 
+several steps required for configuring your project.
+
+> Note: Snapshots contain the latest changes to `conjur-java-api`, but it is recommended
+> to use the current stable release unless there is a significant update required by your
+> project 
+
+1. Add the following to your `settings.xml`
+```xml
+<profiles>
+  <profile>
+     <id>allow-snapshots</id>
+        <activation><activeByDefault>true</activeByDefault></activation>
+     <repositories>
+       <repository>
+         <id>snapshots-repo</id>
+         <url>https://oss.sonatype.org/content/repositories/snapshots</url>
+         <releases><enabled>false</enabled></releases>
+         <snapshots><enabled>true</enabled></snapshots>
+       </repository>
+     </repositories>
+   </profile>
+</profiles>
+```
+
+Alternatively, add the following to your list of repositories in `pom.xml`
+```xml
+<repository>
+  <id>oss.sonatype.org-snapshot</id>
+  <url>http://oss.sonatype.org/content/repositories/snapshots</url>
+  <releases>
+    <enabled>false</enabled>
+  </releases>
+  <snapshots>
+    <enabled>true</enabled>
+  </snapshots>
+</repository>
+```
+
+2. In your `pom.xml`, verify that your `conjur-java-api` dependency includes `SNAPSHOT`
+in the version tag.
+```xml
+<dependency>
+  <groupId>com.cyberark.conjur.api</groupId>
+  <artifactId>conjur-java-api</artifactId>
+  <version>x.x.x-SNAPSHOT</version>
+</dependency>
+```
+
 ## Configuration
 
 Once the setup steps have been successfully run, we will now define the variables needed
@@ -317,7 +381,7 @@ export CONJUR_AUTHN_LOGIN=<user/host identity>
 export CONJUR_AUTHN_API_KEY=<user/host API key or password - see notes about `CONJUR_AUTHN_URL`>
 ```
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 // Configured using environment variables
 Conjur conjur = new Conjur();
@@ -335,7 +399,7 @@ $ java -jar myConjurClient.jar \
      -DCONJUR_AUTHN_API_KEY=<user/host API key - see notes about `CONJUR_AUTHN_URL`>
 ```
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 // Configured using system properties
 Conjur conjur = new Conjur();
@@ -354,7 +418,7 @@ $ mvn exec:java \
   -Dexec.mainClass="com.myorg.client.App"
 ```
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 // Configured using system properties
 Conjur conjur = new Conjur();
@@ -370,7 +434,7 @@ export CONJUR_APPLIANCE_URL=<Conjur endpoint URL>
 ```
 
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 // Authenticate using provided username/hostname and password/API key. See notes about
 // `CONJUR_AUTHN_URL` regarding how 'password-or-api-key' is processed.
@@ -389,8 +453,8 @@ export CONJUR_APPLIANCE_URL=<Conjur endpoint URL>
 ```
 
 ```java
-import net.conjur.api.Conjur;
-import net.conjur.api.Credentials;
+import com.cyberark.conjur.api.Conjur;
+import com.cyberark.conjur.api.Credentials;
 
 // Authenticate using a Credentials object. See notes about `CONJUR_AUTHN_URL`
 // regarding how 'password-or-api-key' is processed.
@@ -410,8 +474,8 @@ export CONJUR_APPLIANCE_URL=<Conjur endpoint URL>
 ```
 
 ```java
-import net.conjur.api.Conjur;
-import net.conjur.api.Token;
+import com.cyberark.conjur.api.Conjur;
+import com.cyberark.conjur.api.Token;
 
 Token token = Token.fromFile(Paths.get('path/to/conjur/authentication/token.json'));
 Conjur conjur = new Conjur(token);
@@ -428,8 +492,8 @@ export CONJUR_APPLIANCE_URL=<Conjur endpoint URL>
 export CONJUR_AUTHN_TOKEN_FILE="path/to/conjur/authentication/token.json"
 ```
 ```java
-import net.conjur.api.Conjur;
-import net.conjur.api.Token;
+import com.cyberark.conjur.api.Conjur;
+import com.cyberark.conjur.api.Token;
 
 Token token = Token.fromEnv();
 Conjur conjur = new Conjur(token);
@@ -443,7 +507,7 @@ To use the client, you will first create an instance of the client and then call
 to send requests to the Conjur API. The most common use case is adding and retrieving
 a secret from Conjur, so we provide some sample code for this use case below.
 
-### Conjur Client Instance (`net.conjur.api.Conjur`)
+### Conjur Client Instance (`com.cyberark.conjur.api.Conjur`)
 
 The client can be instantiated with any of these methods:
 ```java
@@ -471,7 +535,7 @@ Sets a variable to a specific value based on its ID.
 
 Example:
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 Conjur conjur = new Conjur();
 conjur.variables().addSecret(VARIABLE_ID, VARIABLE_VALUE);
@@ -487,7 +551,7 @@ Retireves a variable based on its ID.
 
 Example:
 ```java
-import net.conjur.api.Conjur;
+import com.cyberark.conjur.api.Conjur;
 
 Conjur conjur = new Conjur();
 conjur.variables().retrieveSecret("<VARIABLE_ID>");
@@ -504,7 +568,7 @@ alternative implementation.
 
 ## Troubleshooting
 
-### `error: package net.conjur does not exist`
+### `error: package com.cyberark.conjur does not exist`
 
 This is caused by Maven's (or your dependency resolution tooling) inability to find Conjur
 APIs. Please ensure that you have followed the [setup](#setup) section to properly install

UPGRADING.md

@@ -0,0 +1,60 @@
+# Upgrading Conjur Java API
+
+This guide describes how to upgrade your project to use Conjur Java API.
+
+The main scenario covered in this document is migrating a project with a Conjur-Java-API
+to v3.0.0.
+
+For more details about using the Conjur API, or contributing to development, please
+refer to the [Conjur Java API](https://github.com/cyberark/conjur-api-java).
+
+For further assistance installing and configuring the Conjur Java API,
+please refer to the [Setup](README.md#Setup) section of
+the Conjur Java API [README.md](README.md) file.
+
+## Migrating to 3.0.0
+
+With the update to v.3.0.0, the Conjur Java API now makes use of the `com.cyberark` 
+project namespace. This allows us to publish artifacts to this namespace, which are
+immediately available to use in project. As such, your project can make use of the 
+Conjur Java API without needing to build the Jarfile locally.
+
+### Changes to your code base
+Due to the change to the project namespace, we have modified the package name from 
+`net.conjur.api` to `com.cyberark.conjur.api`. As such, all import statements must be
+updated to reflect this. 
+
+### Example
+Before:
+```java
+import net.conjur.api.AuthnProvider
+``` 
+
+After:
+```java
+import com.cyberark.conjur.api.AuthnProvider
+``` 
+
+### Changes to your `pom.xml`
+Due to the change to the project namespace, we have modified the package name from 
+`net.conjur.api` to `com.cyberark.conjur.api`. As such, your dependency configuration
+must be updated to reflect this. 
+
+### Example
+Before:
+```xml
+<dependency>
+  <groupId>net.conjur.api</groupId>
+  <artifactId>conjur-api</artifactId>
+  <version>2.2.0</version>
+<dependency>
+```
+
+After:
+```xml
+<dependency>
+  <groupId>com.cyberark.conjur.api</groupId>
+  <artifactId>conjur-api</artifactId>
+  <version>3.0.0</version>
+<dependency>
+```

bin/build.sh

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
 set -eo pipefail
 
-
-#TODO - add rest of steps needed to build the package
-
-docker run --rm -v "$PWD:/conjurinc/api-java" -w /conjurinc/api-java maven:3-jdk-8 /bin/bash -c \
-"mvn -X -e clean package -Dmaven.test.skip=true"
+docker run --rm \
+  -v "$PWD:/cyberark/conjur-java-api" \
+  -w /cyberark/conjur-java-api maven:3-jdk-8 \
+  /bin/bash -ec "mvn -X -e clean package -Dmaven.test.skip=true"

bin/deploy-release.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -exo pipefail
+
+# Strip the 'v' from the Tag Name
+export TAG=${TAG_NAME//"v"}
+
+# Deploy release to Sonatype OSSRH (OSS Repository Hosting)
+# Setup: Import our GPG key and passphrase
+# 1. Set the version in the POM to the Tagged Version
+# 2. Sign our build and deploy to OSSRH
+# 3. Release our staged deployment
+#
+# Note: The autoReleaseAfterClose for the nexus-staging-maven-plugin should be
+# set to "false" if we do not want releases published automatically
+docker run --rm \
+  -e OSSRH_USERNAME \
+  -e OSSRH_PASSWORD \
+  -v "$PWD:/cyberark/conjur-java-api" \
+  -v "$GPG_PASSWORD:/gpg_password" \
+  -v "$GPG_PRIVATE_KEY:/gpg_key" \
+  -w /cyberark/conjur-java-api maven:3-jdk-8 \
+  /bin/bash -ec "gpg --batch --passphrase-file /gpg_password --trust-model always --import /gpg_key
+                mvn versions:set -DnewVersion=${TAG}
+                mvn --settings settings.xml clean deploy -Dmaven.test.skip=true -P ossrh,sign
+                mvn nexus-staging:release"

bin/deploy-snapshot.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -exo pipefail
+
+# Deploy snapshot to Sonatype OSSRH (OSS Repository Hosting)
+# Setup: Import our GPG key and passphrase
+# 1. Deploy to snapshot repository of OSSRH
+#
+# Note: Snapshot releases do not need to meet Maven central requirements,
+# but it is best to do so whenever possible
+docker run --rm \
+  -e OSSRH_USERNAME \
+  -e OSSRH_PASSWORD \
+  -v "$PWD:/cyberark/conjur-java-api" \
+  -v "$GPG_PASSWORD:/gpg_password" \
+  -v "$GPG_PRIVATE_KEY:/gpg_key" \
+  -w /cyberark/conjur-java-api maven:3-jdk-8 \
+  /bin/bash -ec "gpg --batch --passphrase-file /gpg_password --trust-model always --import /gpg_key
+                 mvn --settings settings.xml clean deploy -Dmaven.test.skip=true -P ossrh,sign"