Photon v5 updates (#396)

- updated to Gradle v8.5
- migrated from JDK8 to JDK11
- migrated from java.io to java.nio
- migrated from javax to jakarta (where applicable)
- added S3 support via aws-java-nio-spi-for-s3
- consolidated ApplicationComposition, AbstractApplicationComposition and IMFCompositionPlaylistype into IMFCompositionPlaylist
- moved validation code into new package com.netflix.imflibrary.validation
- separated validations for (revisions of) applications, core constraints, cpl and plug-ins
- introduced interface ConstraintsValidator and factory ConstraintsValidatorFactory
- replaced use of SequenceTypeEnum with Strings for SequenceType/Namespace for easier extensibility
- renamed IMPAnalyzer.analyzePackage to IMPAnalyzer.analyzeDelivery to reflect actual scope
- consolidated MXF utility methods in new class MXFUtils
- moved some virtual track validation methods to ConstraintsValidatorUtils, some to core constraints validation classes, and deleted others
- updated CI config with cross platform and multi-JDK builds

---------

Co-authored-by: Adam Pongracz <adamp@colorfront.com>

Author: fschleich

.github/workflows/nebula-ci.yml

@@ -9,32 +9,36 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        # test against JDK 8
-        java: [ 8 ]
-    name: CI with Java ${{ matrix.java }}
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        # test against JDK 11, 17 and 21
+        java: [ 11, 17, 21 ]
+    runs-on: ${{ matrix.os }}
+    name: CI on ${{ matrix.os }} with Java ${{ matrix.java }}
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Setup jdk
-        uses: actions/setup-java@v1
+        uses: actions/setup-java@v4
         with:
+          distribution: 'zulu'
           java-version: ${{ matrix.java }}
-      - uses: actions/cache@v1
+      - uses: actions/cache@v4
         id: gradle-cache
         with:
-          path: ~/.gradle/caches
-          key: ${{ runner.os }}-gradle-${{ hashFiles('**/gradle/dependency-locks/*.lockfile') }}
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+            C:\Users\runneradmin\.gradle\caches
+            C:\Users\runneradmin\.gradle\wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', '**/gradle/dependency-locks/*.lockfile') }}
           restore-keys: |
             - ${{ runner.os }}-gradle-
-      - uses: actions/cache@v1
-        id: gradle-wrapper-cache
-        with:
-          path: ~/.gradle/wrapper
-          key: ${{ runner.os }}-gradlewrapper-${{ hashFiles('gradle/wrapper/*') }}
-          restore-keys: |
-            - ${{ runner.os }}-gradlewrapper-
+
+      - name: Grant execute permission for gradlew
+        if: runner.os != 'Windows'
+        run: chmod +x gradlew
+
       - name: Build with Gradle
         run: ./gradlew --info --stacktrace build
         env:

.github/workflows/nebula-publish.yml

@@ -12,19 +12,20 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - name: Setup jdk 8
-        uses: actions/setup-java@v1
+      - uses: actions/checkout@v4
+      - name: Setup jdk 11
+        uses: actions/setup-java@v2
         with:
-          java-version: 1.8
-      - uses: actions/cache@v1
+          distribution: 'zulu'
+          java-version: 11
+      - uses: actions/cache@v4
         id: gradle-cache
         with:
           path: ~/.gradle/caches
           key: ${{ runner.os }}-gradle-${{ hashFiles('**/gradle/dependency-locks/*.lockfile') }}
           restore-keys: |
             - ${{ runner.os }}-gradle-
-      - uses: actions/cache@v1
+      - uses: actions/cache@v4
         id: gradle-wrapper-cache
         with:
           path: ~/.gradle/wrapper

.github/workflows/nebula-snapshot.yml

@@ -9,20 +9,21 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Set up JDK
-        uses: actions/setup-java@v1
+      - name: Set up JDK 11
+        uses: actions/setup-java@v2
         with:
-          java-version: 8
-      - uses: actions/cache@v2
+          distribution: 'zulu'
+          java-version: 11
+      - uses: actions/cache@v4
         id: gradle-cache
         with:
           path: |
             ~/.gradle/caches
           key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
-      - uses: actions/cache@v2
+      - uses: actions/cache@v4
         id: gradle-wrapper-cache
         with:
           path: |

.gitignore

@@ -76,3 +76,4 @@ secrets/signing-key
 
 # generated java classes
 /generated
+/.tmp.driveupload

CHANGELOG.md

@@ -0,0 +1,15 @@
+## Changes from Photon v4.x to v5
+
+- updated to Gradle v8.5
+- migrated from JDK8 to JDK11
+- migrated from java.io to java.nio
+- migrated from javax to jakarta (where applicable)
+- added S3 support via aws-java-nio-spi-for-s3
+- consolidated ApplicationComposition, AbstractApplicationComposition and IMFCompositionPlaylistype into IMFCompositionPlaylist
+- moved validation code into new package com.netflix.imflibrary.validation
+- separated validations for (revisions of) applications, core constraints, cpl and plug-ins
+- introduced interface ConstraintsValidator and factory ConstraintsValidatorFactory
+- replaced use of SequenceTypeEnum with Strings for SequenceType/Namespace for easier extensibility
+- renamed IMPAnalyzer.analyzePackage to IMPAnalyzer.analyzeDelivery to reflect actual scope
+- consolidated MXF utility methods in new class MXFUtils
+- moved some virtual track validation methods to ConstraintsValidatorUtils, some to core constraints validation classes, and deleted others

README.md

@@ -6,36 +6,41 @@ Photon is a Java implementation of the [Interoperable Master Format (IMF)](https
 - AssetMap (ST 429-9)
 - PackingList (ST 429-8) 
 - Composition Playlist (ST 2067-3) 
-- IMF track files (ST 2067-5)
+- IMF Track Files (ST 2067-5)
 
-Photon parses and reads IMF track files and serializes the metadata into the IMF Composition Playlist structure. Currently, Photon provides support for IMF Application #2E (ST 2067-21) and Application #5 ACES (ST 2067-50), and the Immersive Audio Bitstream (IAB) Plug-in (ST 2067-201).
+Photon parses and reads IMF track files and serializes the metadata into the IMF Composition Playlist structure. Currently, Photon provides support for 
+- IMF Application #2E (ST 2067-21)
+- Application #5 ACES (ST 2067-50)
+- Immersive Audio Bitstream (IAB) Level 0 Plug-in (ST 2067-201).
+- Audio with Frame-based S-ADM Metadata Plug-in (ST 2067-203).
 
 The goal of the Photon is to provide a simple standardized interface to completely validate an IMP.
 
 ## Build
 
 ### JDK requirements
 
-Photon can be built using JDK-8. Support for earlier jdk versions has not been tested and/or verified.
+Photon can be built using JDK-11.
 
 ### Gradle
 Photon can be built very easily by using the included Gradle wrapper. Having downloaded the sources, simply invoke the following commands inside the folder containing the sources:
 
+Linux/macOS:
 ```
 $ ./gradlew clean
 $ ./gradlew build
+$ ./gradlew getDependencies
 ```
 
-For Windows
+Windows:
 ```
 $ gradlew.bat clean
 $ gradlew.bat build
+$ gradlew.bat getDependencies
 ```
 
-## Full Documentation
-
-- [Wiki](https://github.com/Netflix/photon/wiki)
-- [Javadoc](http://netflix.github.io/photon/)
+> [!NOTE]
+> `getDependencies` downloads all dependencies into the `./build/libs` directory.
 
 ## Binaries
 Binaries and dependency information for Maven, Ivy, Gradle and others can be found at [http://search.maven.org](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.netflix.photon%22).
@@ -48,63 +53,57 @@ Example for Maven:
 <dependency>
     <groupId>com.netflix.photon</groupId>
     <artifactId>Photon</artifactId>
-    <version>0.1.1</version>
+    <version>4.10.8</version>
 </dependency>
 ```
 and for Ivy:
 
 ```xml
-<dependency org="com.netflix.photon" name="Photon" rev="0.1.1" />
+<dependency org="com.netflix.photon" name="Photon" rev="4.10.8" />
 ```
 
-If you need to download all dependencies, you just have to run:
-
-```
-$ ./gradlew getDependencies
-```
+## Documentation
 
-It will download all dependencies into ./build/libs directory, where Photon.*.jar is built. Multiple sample applications have been provided with this project (e.g., com.netflix.imflibrary.app.IMFTrackFileReader). Having obtained the dependencies, you can run an application as follows:
+### Sample Applications
+Multiple sample applications have been provided with this project (e.g., com.netflix.imflibrary.app.IMFTrackFileReader). Having obtained the dependencies, you can run an application as follows:
 
+#### Linux/macOS:
 ```
-java -cp ./build/libs/*: <fully qualified class name> <zero or more arguments>
+java -cp "./build/libs/*:" <fully qualified class name> <arguments>
 ```
-E.g.,
+Example:
 ```
-java -cp ./build/libs/*: com.netflix.imflibrary.st0429_9.AssetMap asset_map_file_path
+// Analyze an IMF Delivery locally
+java -cp "./build/libs/*:" com.netflix.imflibrary.app.IMPAnalyzer local_folder_path
+
+// Analyze an IMF Delivery in a S3 bucket
+java -cp "./build/libs/*:" com.netflix.imflibrary.app.IMPAnalyzer s3://path/to/IMFDelivery/
+
+// Analyze an individual IMF asset (e.g. AssetMap, PKL, CPL, MXF Track File)
+java -cp "./build/libs/*:" com.netflix.imflibrary.app.IMPAnalyzer local_file_path
 ```
+
+#### Windows:
 ```
-java -cp ./build/libs/*: com.netflix.imflibrary.st0429_8.PackingList packing_list_file_path
+java -cp build\libs\*; <fully qualified class name> <arguments>
 ```
+Example:
 ```
-java -cp ./build/libs/*: com.netflix.imflibrary.st2067_2.Composition composition_playlist_file_path
+// Analyze an IMF Delivery locally
+java -cp build\libs\*; com.netflix.imflibrary.app.IMPAnalyzer IMP_folder_path
 ```
+### S3 Access
+Photon supports S3 URIs through [aws-java-nio-spi-for-s3](https://github.com/awslabs/aws-java-nio-spi-for-s3). No Photon-specific setup is needed, instead the S3 CLI config and credentials are used directly (see [here](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html) for instructions).
+
+Example (Linux/macOS):
 ```
-java -cp ./build/libs/*: com.netflix.imflibrary.app.IMPAnalyzer IMP_folder_path
+// Analyze an IMF Delivery in a S3 bucket
+java -cp "./build/libs/*:" com.netflix.imflibrary.app.IMPAnalyzer s3://imf-plugfest-imf-plugfest/plugfest_2024_11/source_test_vectors/From_Colorfront/HTJ2K/plugest_FTR_C_EN-XX_US-NR_51_UHD_20241105_OV/
 ```
 
-For Windows please refer to the following examples
 
-To download all dependencies, you just have to run:
+### API and Developer Documentation
 
-```
-$ gradlew.bat getDependencies
-```
-
-It will download all dependencies into build\libs directory, where Photon.*.jar is built. Multiple sample applications have been provided with this project (e.g., com.netflix.imflibrary.app.IMFTrackFileReader). Having obtained the dependencies, you can run an application as follows:
+API documentation is available via [Javadoc](http://netflix.github.io/photon/).
 
-```
-java -cp build\libs\*; <fully qualified class name> <zero or more arguments>
-```
-E.g.,
-```
-java -cp build\libs\*; com.netflix.imflibrary.st0429_9.AssetMap asset_map_file_path
-```
-```
-java -cp build\libs\*; com.netflix.imflibrary.st0429_8.PackingList packing_list_file_path
-```
-```
-java -cp build\libs\*; com.netflix.imflibrary.st2067_2.Composition composition_playlist_file_path
-```
-```
-java -cp build\libs\*; com.netflix.imflibrary.app.IMPAnalyzer IMP_folder_path
-```
+More information is available in the [Wiki](https://github.com/Netflix/photon/wiki).

bootstrap.sh

@@ -92,7 +92,7 @@ cat <<EOT > ${photon_validator_script_to_generate}
 
 set -x 
 
-java -cp ${photon_install_dir}/libs/*:* com.netflix.imflibrary.app.IMPAnalyzer \${1}
+java -cp ${photon_install_dir}/libs/*:* com.netflix.imflibrary.app.IMPAnalyzer \$@}
 
 EOT
 

build.gradle

@@ -1,9 +1,8 @@
 plugins {
-    id 'nebula.netflixoss' version '11.1.1'
     id 'java'
     id 'pmd'
-    id 'com.github.spotbugs' version "4.4.4"
     id 'jacoco'
+    id 'nebula.release' version '20.1.0'
 }
 
 group = 'com.netflix.photon'
@@ -42,25 +41,6 @@ if (JavaVersion.current().isJava8Compatible()) {
 
 repositories {
     mavenCentral()
-    /**
-     * Following represents the location of SNAPSHOTS of RegXMLLib. It should be enabled only when
-     * necessary to verify changes to the library that are not yet committed to Maven Central.
-     */
-    /*maven {
-        url "https://oss.sonatype.org/content/repositories/snapshots/"
-    }*/
-}
-
-spotbugsMain {
-    enabled = true
-    excludeFilter = file("codequality/findbugs-excludeFilter-GeneratedCode.xml")
-    reports {
-        xml.enabled = false
-        html.enabled = true
-    }
-}
-spotbugsTest {
-    enabled = false
 }
 
 pmd {
@@ -87,30 +67,22 @@ javadoc {
 }
 
 dependencies {
-    jaxb "org.glassfish.jaxb:jaxb-xjc:2.2.11"
-
-    compileOnly "com.github.spotbugs:spotbugs-annotations:${spotbugs.toolVersion.get()}"
-    compileOnly "org.slf4j:slf4j-api:latest.release"
-
-    /**
-     * Following includes the RegXMLLib dependency from Maven Central.
-     */
-    implementation "com.sandflow:regxmllib:1.1.5"
-    /**
-     * Following should be enabled and the above should be disabled
-     * when necessary to verify changes to the RegXMLLib library that are
-     * not yet committed to Maven Central.
-     */
-    /*compile "com.sandflow:regxmllib:${revRegXMLSNAPSHOT}"*/
+    implementation 'com.github.spotbugs:spotbugs-annotations:latest.release'
+    implementation "com.sandflow:regxmllib:1.2.+"
     testImplementation "org.mockito:mockito-core:3.3+"
     testImplementation "org.testng:testng:7.5+"
-    implementation "org.slf4j:slf4j-simple:1.7.2"
-    implementation "org.slf4j:slf4j-api:1.7.2"
+    implementation "org.slf4j:slf4j-simple:latest.release"
+    implementation "org.slf4j:slf4j-api:latest.release"
 
+    runtimeOnly 'software.amazon.nio.s3:aws-java-nio-spi-for-s3:latest.release'
 
     // JAX-B dependencies for JDK 9+
-    implementation "jakarta.xml.bind:jakarta.xml.bind-api:2.3.2"
-    implementation "org.glassfish.jaxb:jaxb-runtime:2.3.2"
+    implementation "org.glassfish.jaxb:jaxb-runtime:4.0.5"
+    implementation "jakarta.xml.bind:jakarta.xml.bind-api:4.0.2"
+    implementation 'jakarta.annotation:jakarta.annotation-api:3.0.0'
+
+    // Add JAXB XJC tool for code generation
+    jaxb 'org.glassfish.jaxb:jaxb-xjc:4.0.5'
 }
 
 test {
@@ -130,16 +102,7 @@ task getDependencies(type: Copy) {
 
 jacocoTestReport {
     reports {
-        xml.enabled true
-        html.enabled false
+        xml.required = true
+        html.required = false
     }
 }
-
-//Following line will enable including compile time dependencies as a part of the
-//compile and build process.
-//assemble.dependsOn getDependencies
-java {
-    toolchain {
-        languageVersion = JavaLanguageVersion.of(8)
-    }
-}

gradle/wrapper/gradle-wrapper.properties

@@ -1,7 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionSha256Sum=7ba68c54029790ab444b39d7e293d3236b2632631fb5f2e012bb28b4ff669e4b
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists