Major refactoring (#65)

.github/workflows/build.yml

@@ -9,11 +9,19 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-java@v3
-      with:
-        java-version: '8'
-        distribution: 'temurin'
-        cache: maven
-    - run: mvn -B verify jacoco:report
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v3
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+          cache: maven
+      - run: mvn -B verify
+      - uses: madrapps/[email protected]
+        with:
+          paths: ${{ github.workspace }}/target/site/jacoco/jacoco.xml
+          token: ${{ secrets.GITHUB_TOKEN }}
+          min-coverage-overall: 80
+          min-coverage-changed-files: 80

.github/workflows/codeql-analysis.yml

@@ -23,13 +23,13 @@ jobs:
         language: [ 'java' ]
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
-      with:
-        languages: ${{ matrix.language }}
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.github/workflows/release.yml

@@ -5,32 +5,32 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-java@v3
-      with:
-        java-version: '8'
-        distribution: 'temurin'
-        cache: maven
-        server-id: ossrh
-        server-username: OSSRH_USERNAME
-        server-password: OSSRH_PASSWORD
-        gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
-        gpg-passphrase: GPG_PASSPHRASE
-    - run: |
-        git config user.email "mail@daniel-heid.de"
-        git config user.name "Daniel Heid"
-    - id: version
-      run: |
-        VERSION=$( mvn -B help:evaluate -Dexpression=project.version -q -DforceStdout )
-        echo "::set-output name=version::${VERSION#-SNAPSHOT}"
-    - run: mvn -B release:prepare release:perform
-      env:
-        OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
-        OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
-        GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
-    - uses: release-drafter/release-drafter@v5
-      with:
-        version: ${{ steps.version.outputs.version }}
-        publish: true
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v3
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+          cache: maven
+          server-id: ossrh
+          server-username: OSSRH_USERNAME
+          server-password: OSSRH_PASSWORD
+          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          gpg-passphrase: GPG_PASSPHRASE
+      - run: |
+          git config user.email "matomo-java-tracker@daniel-heid.de"
+          git config user.name "Matomo Java Tracker"
+      - id: version
+        run: |
+          VERSION=$( mvn -B help:evaluate -Dexpression=project.version -q -DforceStdout )
+          echo "::set-output name=version::${VERSION#-SNAPSHOT}"
+      - run: mvn -B release:prepare release:perform
+        env:
+          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+      - uses: release-drafter/release-drafter@v5
+        with:
+          version: ${{ steps.version.outputs.version }}
+          publish: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CODE_OF_CONDUCT.md

@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

CONTRIBUTING.md

@@ -89,4 +89,5 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi
 available at [http://contributor-covenant.org/version/1/4][version]
 
 [homepage]: http://contributor-covenant.org
+
 [version]: http://contributor-covenant.org/version/1/4/

README.md

@@ -9,7 +9,7 @@ Official Java implementation of the [Matomo Tracking HTTP API](https://developer
 
 ## Javadoc
 
-The Javadoc for this project is hosted as a Github page for this repo. The latest Javadoc can be
+The Javadoc for this project is hosted as a GitHub page for this repo. The latest Javadoc can be
 found [here](https://matomo-org.github.io/matomo-java-tracker/javadoc/HEAD/index.html). Javadoc for the latest and all
 releases can be found [here](https://matomo-org.github.io/matomo-java-tracker/javadoc/index.html).
 
@@ -61,13 +61,13 @@ public class YourImplementation {
 
 Per default every request has the following default parameters:
 
-| Parameter Name   | Default Value                  |
-|------------------|--------------------------------|
-| required         | true                           |
-| visitorId        | random 16 character hex string |
-| randomValue      | random 20 character hex string |
-| apiVersion       | 1                              |
-| responseAsImage  | false                          |
+| Parameter Name  | Default Value                  |
+|-----------------|--------------------------------|
+| required        | true                           |
+| visitorId       | random 16 character hex string |
+| randomValue     | random 20 character hex string |
+| apiVersion      | 1                              |
+| responseAsImage | false                          |
 
 Overwrite these properties as desired.
 
@@ -86,7 +86,8 @@ public class YourImplementation {
 
     MatomoRequest request = MatomoRequest.builder()
       .siteId(42)
-      .actionUrl("http://example.org/landing.html?pk_campaign=Email-Nov2011&pk_kwd=LearnMore") // include the query parameters to the url
+      .actionUrl(
+        "http://example.org/landing.html?pk_campaign=Email-Nov2011&pk_kwd=LearnMore") // include the query parameters to the url
       .actionName("LearnMore")
       .build();
   }
@@ -153,7 +154,8 @@ public class YourImplementation {
 
   public void yourMethod() {
 
-    MatomoRequest request = MatomoRequest.builder().siteId(42).actionUrl("https://www.mydomain.com/some/page").actionName("Signup").build();
+    MatomoRequest request =
+      MatomoRequest.builder().siteId(42).actionUrl("https://www.mydomain.com/some/page").actionName("Signup").build();
 
     MatomoTracker tracker = new MatomoTracker("https://your-matomo-domain.tld/matomo.php");
     try {
@@ -183,7 +185,6 @@ package example;
 
 import org.apache.http.HttpResponse;
 import org.matomo.java.tracking.MatomoRequest;
-import org.matomo.java.tracking.MatomoRequestBuilder;
 import org.matomo.java.tracking.MatomoTracker;
 
 import java.io.IOException;
@@ -232,7 +233,6 @@ package example;
 import org.apache.http.HttpResponse;
 import org.matomo.java.tracking.MatomoLocale;
 import org.matomo.java.tracking.MatomoRequest;
-import org.matomo.java.tracking.MatomoRequestBuilder;
 import org.matomo.java.tracking.MatomoTracker;
 
 import java.io.IOException;
@@ -250,11 +250,15 @@ public class YourImplementation {
     Collection<MatomoRequest> requests = new ArrayList<>();
     MatomoRequestBuilder builder = MatomoRequest.builder().siteId(42);
     requests.add(builder.actionUrl("https://www.mydomain.com/some/page").actionName("Some Page").build());
-    requests.add(builder.actionUrl("https://www.mydomain.com/another/page").actionName("Another Page").visitorCountry(new MatomoLocale(Locale.GERMANY)).build());
+    requests.add(builder.actionUrl("https://www.mydomain.com/another/page").actionName("Another Page")
+      .visitorCountry(new MatomoLocale(Locale.GERMANY)).build());
 
     MatomoTracker tracker = new MatomoTracker("https://your-matomo-domain.tld/matomo.php");
     try {
-      Future<HttpResponse> response = tracker.sendBulkRequestAsync(requests, "33dc3f2536d3025974cccb4b4d2d98f4"); // second parameter is authentication token need for country override
+      Future<HttpResponse> response = tracker.sendBulkRequestAsync(
+        requests,
+        "33dc3f2536d3025974cccb4b4d2d98f4"
+      ); // second parameter is authentication token need for country override
       // usually not needed:
       HttpResponse httpResponse = response.get();
       int statusCode = httpResponse.getStatusLine().getStatusCode();
@@ -274,6 +278,80 @@ public class YourImplementation {
 
 ```
 
+## Migration from Version 2 to 3
+
+We improved this library by adding the dimension parameter and removing outdated parameters in Matomo version 5,
+removing some dependencies (that even contained vulnerabilities) and increasing maintainability. Sadly this includes the
+following breaking changes:
+
+### Removals
+
+* The parameter `actionTime` (`gt_ms`) is no longer supported by Matomo 5 and was removed.
+* Many methods marked as deprecated in version 2 were removed. Please see the
+  former [Javadoc](https://matomo-org.github.io/matomo-java-tracker/javadoc/HEAD/index.html) of version 2 to get the
+  deprecated methods.
+* We removed the vulnerable dependency to the Apache HTTP client. Callbacks are no longer of type `FutureCallback`, but
+  `Consumer<Void>` instead.
+* The `send...` methods of `MatomoTracker` no longer return a value (usually Matomo always returns an HTTP 204 response
+  without a body). If the request fails, an exception will be thrown.
+* Since there are several ways on how to set the auth token, `verifyAuthTokenSet` was removed. Just check yourself,
+  whether your auth token is null. However, the tracker checks, whether an auth token is either set by parameter, by
+  request or per configuration.
+* Due to a major refactoring on how the queries are created, we no longer use a large map instead of concrete attributes
+  to collect the Matomo parameters. Therefore `getParameters()` of class `MatomoRequest` no longer exists. Please use
+  getters and setters instead.
+* The methods `verifyEcommerceEnabled()` and `verifyEcommerceState()` were removed from `MatomoRequest`. The request
+  will be validated prior to sending and not during construction.
+* `getRandomHexString` was removed. Use `RandomValue.random()` or `VisitorId.random()` instead.
+
+## Type Changes and Renaming
+
+* `requestDatetime`, `visitorPreviousVisitTimestamp`, `visitorFirstVisitTimestamp`, `ecommerceLastOrderTimestamp` are
+  now of type `Instant`. You can use `Instant.ofEpochSecond()` to create
+  them from epoch seconds.
+* `requestDatetime` was renamed to `requestTimestamp` due to setter collision and downwards compatibility
+* `goalRevenue` is the same parameter as `ecommerceRevenue` and was removed to prevent duplication.
+  Use `ecommerceRevenue` instead.
+* `setEventValue` requires a double parameter now
+* `setEcommerceLastOrderTimestamp` requires an `Instant` parameter now
+* `headerAcceptLanguage` is now of type `AcceptLanguage`. You can build it easily
+  using `AcceptLanguage.fromHeader("de")`
+* `visitorCountry` is now of type `Country`. You can build it easily using `AcceptLanguage.fromCode("fr")`
+* `deviceResolution` is now of type `DeviceResolution`. You can build it easily
+  using `DeviceResolution.builder.width(...).height(...).build()`. To easy the migration, we added a constructor
+  method `DeviceResolution.fromString()` that accepts inputs of kind _width_x_height_, e.g. `100x200`
+* `pageViewId` is now of type `UniqueId`. You can build it easily using `UniqueId.random()`
+* `randomValue` is now of type `RandomValue`. You can build it easily using `RandomValue.random()`. However, if you
+  really
+  want to insert a custom string here, use `RandomValue.fromString()` construction method.
+* URL was removed due to performance and complicated exception handling and problems with parsing of complex
+  URLs. `actionUrl`, `referrerUrl`, `outlinkUrl`, `contentTarget` and `downloadUrl` are now strings.
+* `getCustomTrackingParameter()` of `MatomoRequest` returns an unmodifiable list now.
+* Instead of `IllegalStateException` the tracker throws `MatomoException`
+* In former versions the goal id had always to be zero or null. You can now define higher numbers than zero.
+* For more type changes see the sections below.
+
+### Visitor ID
+
+* `visitorId` and `visitorCustomId` are now of type `VisitorId`. You can build them easily
+  using `VisitorId.fromHash(...)`.
+* You can use `VisitorId.fromHex()` to create a `VisitorId` from a string that contains only hexadecimal characters.
+* VisitorId.fromHex() now supports less than 16 hexadecimal characters. If the string is shorter than 16 characters,
+  the remaining characters will be filled with zeros.
+
+### Custom Variables
+
+* According to Matomo, custom variables should no longer be used. Please use dimensions instead. Dimension support has
+  been introduced.
+* `CustomVariable` is now in package `org.matomo.java.tracking.parameters`.
+* `customTrackingParameters` in `MatomoRequestBuilder` requires a `Map<String, Collection<String>>` instead
+  of `Map<String, String>` now
+* `pageCustomVariables` and `visitCustomVariables` are now of type `CustomVariables` instead of collections. Create them
+  with `CustomVariables.builder().variable(customVariable)`
+* `setPageCustomVariable` and `getPageCustomVariable` now longer accept a string as an index. Please use integers
+  instead.
+* Custom variables will now be sent URL encoded
+
 ## Building
 
 You need a GPG signing key on your machine. Please follow these
@@ -285,8 +363,8 @@ This project can be tested and built by calling
 mvn install
 ```
 
-The built jars and javadoc can be found in `target`. By using the install Maven goal, the snapshot
-version can be used using your local Maven repository for testing purposes, e.g.
+The built jars and javadoc can be found in `target`. By using the Maven goal `install, the snapshot
+version can be used in your local Maven repository for testing purposes, e.g.
 
 ```xml