azam · azam · May 14, 2023 · May 14, 2023 · May 14, 2023 · May 14, 2023
diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml
@@ -0,0 +1,50 @@
+name: bench
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  schedule:
+    - cron: '0 9 * * 4'
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: bench-${{matrix.name}}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - name: jdk8
+            version: 8
+            distribution: temurin
+          - name: jdk11
+            version: 11
+            distribution: temurin
+          - name: jdk16
+            version: 16
+            distribution: temurin
+          - name: jdk17
+            version: 17
+            distribution: temurin
+    steps:
+      - name: checkout-${{matrix.name}}
+        uses: actions/checkout@v2
+      - name: setup-toolchain-${{matrix.name}}
+        uses: actions/setup-java@v2
+        with:
+          java-version: ${{matrix.version}}
+          distribution: ${{matrix.distribution}}
+          cache: maven
+      - name: build-${{matrix.name}}
+        run: mvn -P benchmark clean package -B -V
+      - name: benchmark-${{matrix.name}}
+        run: java -jar target/benchmark.jar AzamCodecBench -rf json
+      - name: upload-bench-results-${{matrix.name}}
+        uses: actions/upload-artifact@v1
+        with:
+          name: azamcodec_bench_${{matrix.name}}_${{github.sha}}
+          path: ./jmh-result.json
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -18,13 +18,10 @@ on:
 
 jobs:
   test:
-    name: test-${{matrix.distribution}}-${{matrix.version}}
+    name: test-${{matrix.name}}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        name:
-          - jdk8
-          - jdk11
         include:
           - name: jdk8
             version: 8
@@ -48,4 +45,4 @@ jobs:
           distribution: ${{matrix.distribution}}
           cache: maven
       - name: verify-${{matrix.name}}
-        run: mvn verify --settings .settings.xml -Dgpg.skip -B -V
+        run: mvn clean verify --settings .settings.xml -Dgpg.skip -B -V
diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
@@ -34,4 +34,4 @@ jobs:
           MAVEN_PASSWORD: ${{secrets.MAVEN_PASSWORD}}
           MAVEN_GPG_KEYNAME: ${{secrets.MAVEN_GPG_KEYNAME}}
           MAVEN_GPG_PASSPHRASE: ${{secrets.MAVEN_GPG_PASSPHRASE}}
-        run: mvn package -P release --batch-mode --settings .settings.xml -DskipTests=true -DperformRelease=false -Dmaven.deploy.skip=true --update-snapshots -B -V
+        run: mvn clean package -P release --batch-mode --settings .settings.xml -DskipTests=true -DperformRelease=false -Dmaven.deploy.skip=true --update-snapshots -B -V
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -33,7 +33,7 @@ jobs:
           MAVEN_PASSWORD: ${{secrets.MAVEN_PASSWORD}}
           MAVEN_GPG_KEYNAME: ${{secrets.MAVEN_GPG_KEYNAME}}
           MAVEN_GPG_PASSPHRASE: ${{secrets.MAVEN_GPG_PASSPHRASE}}
-        run: mvn deploy -P release --batch-mode --settings .settings.xml -DperformRelease=false --update-snapshots -B -V
+        run: mvn clean deploy -P release --batch-mode --settings .settings.xml -DperformRelease=false --update-snapshots -B -V
       - name: artifacts
         uses: softprops/action-gh-release@v1
         with:

diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+jmh-result.json
+
 # https://github.com/github/gitignore/blob/master/Java.gitignore
 
 # Compiled class file

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,16 @@
+{
+  "java.format.settings.profile": "GoogleStyle",
+  "java.format.settings.url": "./eclipse-java-google-style.xml",
+  "java.configuration.updateBuildConfiguration": "automatic",
+  "[java]": {
+    "editor.formatOnSave": true,
+    "editor.detectIndentation": false,
+    "editor.insertSpaces": true,
+    "editor.tabSize": 2
+  },
+  "[xml]": {
+    "editor.detectIndentation": false,
+    "editor.insertSpaces": true,
+    "editor.tabSize": 2
+  }
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,37 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "clean",
+            "type": "shell",
+            "command": "mvn -B clean",
+            "group": "build"
+        },
+        {
+            "label": "format",
+            "type": "shell",
+            "command": "mvn -B formatter:format xml-format:xml-format",
+            "group": "build"
+        },
+        {
+            "label": "verify",
+            "type": "shell",
+            "command": "mvn -B verify",
+            "group": "build"
+        },
+        {
+            "label": "test",
+            "type": "shell",
+            "command": "mvn -B test",
+            "group": "test"
+        },
+        {
+            "label": "bench",
+            "type": "shell",
+            "command": "mvn -B -P benchmark package && java -jar ${workspaceFolder}/target/benchmark.jar AzamCodecBench -rf json",
+            "group": "test"
+        }
+    ]
+}
diff --git a/README.md b/README.md
@@ -19,27 +19,67 @@ This library is published to [Maven Central](https://central.sonatype.com/artifa
 
 ```java
 // Decode to ints
-int[] ints = AzamCodec.azamDecodeAllInts("");
+int[] ints = AzamCodec.azamDecodeInts("xytxvyyfh5wgg1"); // -559038737, 21, 49153
 
 // Decode to big endian bytes
-byte[] bytes = AzamCodec.azamDecodeAllBytes("");
+byte[][] bytes = AzamCodec.azamDecodeBytes("xytxvyyfh5wgg1"); // 0xdeadbeef, 0x15, 0xc001
 ```
 
 ### Encoding
 
 ```java
 // Encode from ints
-String encodedInts = AzamCodec.azamEncodeInts(new int[]{});
+String encodedInts = AzamCodec.azamEncodeInts(new int[]{ -559038737, 21, 49153 }); // "xytxvyyfh5wgg1"
 
 // Encode from bytes
-String encodedBytes = AzamCodec.azamEncodeBytes(new byte[][]{});
+String encodedBytes = AzamCodec.azamEncodeBytes(new byte[][]{ //
+    new byte[] { 0xde, 0xad, 0xbe, 0xef }, //
+    new byte[] { 0x15 }, //
+    new byte[] { 0xc0, 0x01 } //
+}); // "xytxvyyfh5wgg1"
+```
+
+### Practical example
+
+Azam Codec is designed to be a sortable identifier representation, so using it to represent multi sectioned identifier is the best example.
+
+```java
+public class RecordId {
+  int tenantId;
+  int objectId;
+  int recordId;
+
+  public RecordId(String id) throws ParseException {
+    int[] sections = AzamCodec.azamDecodeInts(id);
+    this.tenantId = sections[0];
+    this.objectId = sections[1];
+    this.recordId = sections[2];
+  }
+
+  public String toString() {
+    return AzamCodec.azamEncodeInts(new int[] { this.tenantId, this.objectId, this.recordId });
+  }
+}
 ```
 
 ## Development
 
 Standard Java development method applies.
-Please run the following before sending a PR:
+Please make sure that code is correctly formatted and tests are passing before sending a PR.
 
-* You can format sources to match style with ```mvn formatter:format xml-format:xml-format```
-  * You can also use VS Code extension
-* Make sure tests are passing and source is properly formatted by running ```mvn verify```
+### Format source code
+```sh
+mvn formatter:format xml-format:xml-format
+```
+
+### Test
+```sh
+mvn verify
+```
+
+### Benchmark
+
+```sh
+mvn -P benchmark package
+java -jar target/benchmark.jar AzamCodecBench
+```
diff --git a/pom.xml b/pom.xml
@@ -3,7 +3,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>io.azam.azamcodec</groupId>
   <artifactId>azamcodec</artifactId>
-  <version>0.0.1</version>
+  <version>0.1.0</version>
   <name>azamcodec</name>
   <description>An encoder and decoder implementation in Java for Azam Codec, a lexicographically sortable multi-section base16 encoding of byte array.</description>
   <url>https://github.com/azam/azamcodec-java</url>
@@ -52,6 +52,18 @@
       <version>4.13.1</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-core</artifactId>
+      <version>1.36</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.openjdk.jmh</groupId>
+      <artifactId>jmh-generator-annprocess</artifactId>
+      <version>1.36</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
   <build>
     <plugins>
@@ -73,13 +85,35 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>build-helper-maven-plugin</artifactId>
+        <version>3.4.0</version>
+        <executions>
+          <execution>
+            <id>add-bench-source</id>
+            <phase>generate-test-sources</phase>
+            <goals>
+              <goal>add-test-source</goal>
+            </goals>
+            <configuration>
+              <sources>
+                <source>src/bench/java</source>
+              </sources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>2.10.4</version>
         <configuration>
-          <!-- Setting this to 7 removes unnamed modules found warnings -->
+          <!-- Setting this to 7 removes unnamed modules found warnings, since we are targeting 1.7 -->
           <source>7</source>
+          <sourceFileExcludes>
+            <sourceFileExclude>target/generated-test-sources</sourceFileExclude>
+          </sourceFileExcludes>
         </configuration>
         <executions>
           <execution>
@@ -191,5 +225,86 @@
         </plugins>
       </build>
     </profile>
+    <profile>
+      <id>benchmark</id>
+      <activation>
+        <activeByDefault>false</activeByDefault>
+      </activation>
+      <properties>
+        <skipTests>true</skipTests>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
+      </properties>
+      <dependencies>
+        <dependency>
+          <groupId>org.openjdk.jmh</groupId>
+          <artifactId>jmh-core</artifactId>
+          <version>1.36</version>
+        </dependency>
+        <dependency>
+          <groupId>org.openjdk.jmh</groupId>
+          <artifactId>jmh-generator-annprocess</artifactId>
+          <version>1.36</version>
+        </dependency>
+      </dependencies>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.6.0</version>
+            <configuration>
+              <compileSourceRoots>
+                <compileSourceRoot>${project.basedir}/src/main/java</compileSourceRoot>
+                <compileSourceRoot>${project.basedir}/src/bench/java</compileSourceRoot>
+              </compileSourceRoots>
+              <annotationProcessorPaths>
+                <path>
+                  <groupId>org.openjdk.jmh</groupId>
+                  <artifactId>jmh-generator-annprocess</artifactId>
+                  <version>1.36</version>
+                </path>
+              </annotationProcessorPaths>
+            </configuration>
+          </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-shade-plugin</artifactId>
+            <version>3.4.1</version>
+            <executions>
+              <execution>
+                <phase>package</phase>
+                <goals>
+                  <goal>shade</goal>
+                </goals>
+                <configuration>
+                  <!-- <finalName>${project.artifactId}-${project.version}-benchmark</finalName> -->
+                  <finalName>benchmark</finalName>
+                  <transformers>
+                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                      <mainClass>org.openjdk.jmh.Main</mainClass>
+                    </transformer>
+                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                  </transformers>
+                  <filters>
+                    <filter>
+                      <!--
+                        Shading signed JARs will fail without this.
+                        http://stackoverflow.com/questions/999489/invalid-signature-file-when-attempting-to-run-a-jar
+                      -->
+                      <artifact>*:*</artifact>
+                      <excludes>
+                        <exclude>META-INF/*.SF</exclude>
+                        <exclude>META-INF/*.DSA</exclude>
+                        <exclude>META-INF/*.RSA</exclude>
+                      </excludes>
+                    </filter>
+                  </filters>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
   </profiles>
 </project>