Refactor in preparation for supporting POI and ENTITIES MCA files

.github/workflows/gradle-publish.yml

@@ -0,0 +1,44 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will build a package using Gradle and then publish it to GitHub packages when a release is created
+# For more information see: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#Publishing-using-gradle
+
+name: Gradle Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up JDK 17
+      uses: actions/setup-java@v4
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+        server-id: github # Value of the distributionManagement/repository/id field of the pom.xml
+        settings-path: ${{ github.workspace }} # location for the settings.xml file
+
+    - name: Setup Gradle
+      uses: gradle/actions/setup-gradle@417ae3ccd767c252f5661f1ace9f835f9654f2b5 # v3.1.0
+
+    - name: Build with Gradle
+      run: ./gradlew build
+
+    # The USERNAME and TOKEN need to correspond to the credentials environment variables used in
+    # the publishing section of your build.gradle
+    - name: Publish to GitHub Packages
+      run: ./gradlew publish
+      env:
+        USERNAME: ${{ github.actor }}
+        TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -87,3 +87,7 @@ doc/
 out/
 
 *.patch
+TESTDBG/
+ScratchpadTest.java
+/.run/publishToMavenLocal.run.xml
+/nbt-profiling-run.jfr

README.md

@@ -1,30 +1,89 @@
 # NBT
-[![Build Status](https://travis-ci.org/Querz/NBT.svg?branch=master)](https://travis-ci.org/Querz/NBT) [![Coverage Status](https://img.shields.io/coveralls/github/Querz/NBT/master.svg)](https://coveralls.io/github/Querz/NBT?branch=master) [![Release](https://jitpack.io/v/Querz/NBT.svg)](https://jitpack.io/#Querz/NBT)
-#### A java implementation of the [NBT protocol](http://minecraft.gamepedia.com/NBT_format) for Minecraft Java Edition.
+<!-- [![Build Status](https://travis-ci.org/Querz/NBT.svg?branch=master)](https://travis-ci.org/Querz/NBT) [![Coverage Status](https://img.shields.io/coveralls/github/Querz/NBT/master.svg)](https://coveralls.io/github/Querz/NBT?branch=master) [![Release](https://jitpack.io/v/Querz/NBT.svg)](https://jitpack.io/#Querz/NBT) -->
+A java implementation of the [NBT protocol](https://minecraft.gamepedia.com/NBT_format) for Minecraft Java Edition.
+
+**!!! THIS FORK IS UNDER HEAVY DEVELOPMENT - May 2024!!!**
+
+But, it is ready for early adopters!
+
+This library includes a rich [NBT](https://minecraft.gamepedia.com/NBT_format) experience and powerful tools
+for working with .mca files. The NBT portion is largely stable while the mca library is still going through heavy
+iteration.
+
+#### Highlights of the NBT library
+* [NbtPath](src/main/java/io/github/ensgijs/nbt/query/NbtPath.java) Allows you to easily get and put nested tags.
+* [TextNbtHelpers](src/main/java/io/github/ensgijs/nbt/io/TextNbtHelpers.java) Utilities for reading and writing text nbt data - with pretty printing! Yes, pretty printed text nbt data is also parseable.
+* [BinaryNbtHelpers](src/main/java/io/github/ensgijs/nbt/io/BinaryNbtHelpers.java) Utilities for working with binary nbt files, compressed or uncompressed.
+
+#### Highlights of the MCA library
+* Version support from Minecraft Java 1.9.0 to 1.21.3 and beyond (no Bedrock support currently or planed at this time).
+  * [DataVersion](src/main/java/io/github/ensgijs/nbt/mca/DataVersion.java) nearly complete data version to minecraft version mapping and detection back to 1.9.0.
+* Rich javadocs on most classes and methods.
+* Excellent code coverage and extensive unit testing as well as integration testing for multiple Minecraft versions see [test resources](src/test/resources)
+  * _There's always room for improvement of the richness of integration data samples - some of the samples are a little less interesting than I would prefer._
+* Supports editing of non-vanilla world files without data loss.
+* Support for terrain (region), entities, and poi mca files - the various chunk class types are due for a heavy refactor, and I plan to add an abstraction layer to wrap all 3 mca/chunk types to provide a more seamless processing / editing experience.
+* Safely relocate (move) chunks - all chunk implementations fully support being moved to a new location. All contents are updated to exist in the new chunk location. This feature is the primary reason I dusted off this project after 3 years and is well tested and very ready for consumption.
+  * [RegionFileRelocator](src/main/java/io/github/ensgijs/nbt/mca/io/RegionFileRelocator.java) relocate entire region files.
+* Multiple options for reading and writing chunk data to .mca files using one of the following classes.
+  * [RandomAccessMcaFile](src/main/java/io/github/ensgijs/nbt/mca/io/RandomAccessMcaFile.java) read and write chunks with minimal memory overhead.
+  * [McaFileChunkIterator](src/main/java/io/github/ensgijs/nbt/mca/io/McaFileChunkIterator.java) iterate through the chunks in an mca file one after the other, again keeping memory overhead down.
+  * [McaFileStreamingWriter](src/main/java/io/github/ensgijs/nbt/mca/io/McaFileStreamingWriter.java) write an entire mca file one chunk at a time.
+
+#### Powerful Utilities
+* [LongArrayTagPackedIntegers](src/main/java/io/github/ensgijs/nbt/mca/util/LongArrayTagPackedIntegers.java) a comprehensive solution to working with all long[] packed values (block palettes, biome palettes, Heightmaps) across all DataVersions.
+* [PalettizedCuboid](src/main/java/io/github/ensgijs/nbt/mca/util/PalettizedCuboid.java) powerful class for working with block and biome palettes. This class supports all MC versions that use data palettes; I may add block and biome child classes to improve usability in the future.
+
+#### How to get started with 0.1-SNAPSHOT
+This package is not yet published to a public repository - but using it from a local build is easy!
+
+Download the source, open the project in your IDE of choice (Intellij, etc), run the gradle rule
+`gradle publishToMavenLocal` to build the source and stash the 0.1-SNAPSHOT in your local maven cache.
+
+Gradle:
+```
+dependencies {
+	...
+	implementation 'io.github.ensgijs:ens-nbt:0.1-SNAPSHOT'
+}
+```
+
+Maven:
+```
+<dependency>
+    <groupId>io.github.ensgijs</groupId>
+    <artifactId>ens-nbt</artifactId>
+    <version>0.1-SNAPSHOT</version>
+    <scope>compile</scope>
+</dependency>
+```
+
+
 ---
-### Specification
+### NBT Specification
 According to the [specification](https://minecraft.gamepedia.com/NBT_format), there are currently 13 different types of tags:
 
 | Tag class    | Superclass | ID | Payload |
 | ---------    | ---------- | -- | ----------- |
-| [EndTag](src/main/java/net/querz/nbt/EndTag.java)             | [Tag](src/main/java/net/querz/nbt/Tag.java)               | 0  | None |
-| [ByteTag](src/main/java/net/querz/nbt/ByteTag.java)           | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 1  | 1 byte / 8 bits, signed |
-| [ShortTag](src/main/java/net/querz/nbt/ShortTag.java)         | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 2  | 2 bytes / 16 bits, signed, big endian |
-| [IntTag](src/main/java/net/querz/nbt/IntTag.java)             | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 3  | 4 bytes / 32 bits, signed, big endian |
-| [LongTag](src/main/java/net/querz/nbt/LongTag.java)           | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 4  | 8 bytes / 64 bits, signed, big endian |
-| [FloatTag](src/main/java/net/querz/nbt/FloatTag.java)         | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 5  | 4 bytes / 32 bits, signed, big endian, IEEE 754-2008, binary32 |
-| [DoubleTag](src/main/java/net/querz/nbt/DoubleTag.java)       | [NumberTag](src/main/java/net/querz/nbt/NumberTag.java)   | 6  | 8 bytes / 64 bits, signed, big endian, IEEE 754-2008, binary64 |
-| [ByteArrayTag](src/main/java/net/querz/nbt/ByteArrayTag.java) | [ArrayTag](src/main/java/net/querz/nbt/ArrayTag.java)     | 7  | `IntTag` payload *size*, then *size* `ByteTag` payloads |
-| [StringTag](src/main/java/net/querz/nbt/StringTag.java)       | [Tag](src/main/java/net/querz/nbt/Tag.java)               | 8  | `ShortTag` payload *length*, then a UTF-8 string with size *length* |
-| [ListTag](src/main/java/net/querz/nbt/ListTag.java)           | [Tag](src/main/java/net/querz/nbt/Tag.java)               | 9  | `ByteTag` payload *tagId*, then `IntTag` payload *size*, then *size* tags' payloads, all of type *tagId* |
-| [CompoundTag](src/main/java/net/querz/nbt/CompoundTag.java)   | [Tag](src/main/java/net/querz/nbt/Tag.java)               | 10 | Fully formed tags, followed by an `EndTag` |
-| [IntArrayTag](src/main/java/net/querz/nbt/IntArrayTag.java)   | [ArrayTag](src/main/java/net/querz/nbt/ArrayTag.java)     | 11 | `IntTag` payload *size*, then *size* `IntTag` payloads |
-| [LongArrayTag](src/main/java/net/querz/nbt/LongArrayTag.java) | [ArrayTag](src/main/java/net/querz/nbt/ArrayTag.java)     | 12 | `IntTag` payload *size*, then *size* `LongTag` payloads |
+| [EndTag](src/main/java/io/github/ensgijs/nbt/tag/EndTag.java)             | [Tag](src/main/java/io/github/ensgijs/nbt/tag/Tag.java)               | 0  | None |
+| [ByteTag](src/main/java/io/github/ensgijs/nbt/tag/ByteTag.java)           | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 1  | 1 byte / 8 bits, signed |
+| [ShortTag](src/main/java/io/github/ensgijs/nbt/tag/ShortTag.java)         | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 2  | 2 bytes / 16 bits, signed, big endian |
+| [IntTag](src/main/java/io/github/ensgijs/nbt/tag/IntTag.java)             | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 3  | 4 bytes / 32 bits, signed, big endian |
+| [LongTag](src/main/java/io/github/ensgijs/nbt/tag/LongTag.java)           | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 4  | 8 bytes / 64 bits, signed, big endian |
+| [FloatTag](src/main/java/io/github/ensgijs/nbt/tag/FloatTag.java)         | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 5  | 4 bytes / 32 bits, signed, big endian, IEEE 754-2008, binary32 |
+| [DoubleTag](src/main/java/io/github/ensgijs/nbt/tag/DoubleTag.java)       | [NumberTag](src/main/java/io/github/ensgijs/nbt/tag/NumberTag.java)   | 6  | 8 bytes / 64 bits, signed, big endian, IEEE 754-2008, binary64 |
+| [ByteArrayTag](src/main/java/io/github/ensgijs/nbt/tag/ByteArrayTag.java) | [ArrayTag](src/main/java/io/github/ensgijs/nbt/tag/ArrayTag.java)     | 7  | `IntTag` payload *size*, then *size* `ByteTag` payloads |
+| [StringTag](src/main/java/io/github/ensgijs/nbt/tag/StringTag.java)       | [Tag](src/main/java/io/github/ensgijs/nbt/tag/Tag.java)               | 8  | `ShortTag` payload *length*, then a UTF-8 string with size *length* |
+| [ListTag](src/main/java/io/github/ensgijs/nbt/tag/ListTag.java)           | [Tag](src/main/java/io/github/ensgijs/nbt/tag/Tag.java)               | 9  | `ByteTag` payload *tagId*, then `IntTag` payload *size*, then *size* tags' payloads, all of type *tagId* |
+| [CompoundTag](src/main/java/io/github/ensgijs/nbt/tag/CompoundTag.java)   | [Tag](src/main/java/io/github/ensgijs/nbt/tag/Tag.java)               | 10 | Fully formed tags, followed by an `EndTag` |
+| [IntArrayTag](src/main/java/io/github/ensgijs/nbt/tag/IntArrayTag.java)   | [ArrayTag](src/main/java/io/github/ensgijs/nbt/tag/ArrayTag.java)     | 11 | `IntTag` payload *size*, then *size* `IntTag` payloads |
+| [LongArrayTag](src/main/java/io/github/ensgijs/nbt/tag/LongArrayTag.java) | [ArrayTag](src/main/java/io/github/ensgijs/nbt/tag/ArrayTag.java)     | 12 | `IntTag` payload *size*, then *size* `LongTag` payloads |
 
 * The `EndTag` is only used to mark the end of a `CompoundTag` in its serialized state or an empty `ListTag`.
 
 * The maximum depth of the NBT structure is 512. If the depth exceeds this restriction during serialization, deserialization or String conversion, a `MaxDepthReachedException` is thrown. This usually happens when a circular reference exists in the NBT structure. The NBT specification does not allow circular references, as there is no tag to represent this.
 
+<!--
 ### Add the library as a dependency using Gradle:
 Add Jitpack to your `repositories`:
 ```
@@ -37,7 +96,7 @@ And then add it as a dependency as usual:
 ```
 dependencies {
 	...
-	implementation 'com.github.Querz:NBT:6.1'
+	implementation 'com.github.ens-gijs:NBT:1.0'
 }
 ```
 
@@ -54,9 +113,9 @@ Add Jitpack:
 Dependency:
 ```
 <dependency>
-	<groupId>com.github.Querz</groupId>
+	<groupId>com.github.ens-gijs</groupId>
 	<artifactId>NBT</artifactId>
-	<version>6.1</version>
+	<version>1.0</version>
 </dependency>
 ```
 
@@ -83,7 +142,7 @@ All methods serializing instances or deserializing data track the nesting levels
 
 These methods have a parameter for the maximum nesting depth they are allowed to traverse. A value of `0` means that only the object itself, but no nested object may be processed.
 
-If an instance is nested further than allowed, a [MaxDepthReachedException](src/main/java/net/querz/nbt/MaxDepthReachedException.java) will be thrown. A negative maximum depth will cause an `IllegalArgumentException`.
+If an instance is nested further than allowed, a [MaxDepthReachedException](src/main/java/io/github/ensgijs/io/MaxDepthReachedException.java) will be thrown. A negative maximum depth will cause an `IllegalArgumentException`.
 
 Some methods do not provide a parameter to specify the maximum depth, but instead use `Tag.DEFAULT_MAX_DEPTH` (`512`) which is also the maximum used in Minecraft.
 
@@ -150,3 +209,4 @@ mcaFile.cleanupPalettesAndBlockStates();
 chunk.cleanupPalettesAndBlockStates();
 section.cleanupPaletteAndBlockStates();
 ```
+-->

build.gradle

@@ -1,56 +1,124 @@
 plugins {
 	id 'com.github.kt3k.coveralls' version '2.4.0'
-	id 'maven'
+	id 'maven-publish'
+	// Add the JMH Gradle plugin
+	id 'me.champeau.jmh' version '0.7.1'
 }
 
 apply plugin: 'java'
 apply plugin: 'eclipse'
 apply plugin: 'idea'
 apply plugin: 'jacoco'
 
-group                        = 'net.querz.nbt'
-archivesBaseName             = 'nbt'
-version                      = '6.1'
-sourceCompatibility          = '1.8'
-targetCompatibility          = '1.8'
+group = 'io.github.ensgijs'
+archivesBaseName = 'ens-nbt'
+version = '0.1-SNAPSHOT'
+sourceCompatibility = JavaLanguageVersion.of(17)
+targetCompatibility = JavaLanguageVersion.of(17)
 compileJava.options.encoding = 'UTF-8'
+compileTestJava.options.encoding = 'UTF-8'
 
 repositories {
-	jcenter()
+	mavenCentral()
+}
+
+publishing {
+	repositories {
+		maven {
+			name = "GitHubPackages"
+			url = "https://maven.pkg.github.com/octocat/hello-world"
+			credentials {
+				username = System.getenv("GITHUB_ACTOR")
+				password = System.getenv("GITHUB_TOKEN")
+			}
+		}
+	}
+	publications {
+		maven(MavenPublication) {
+			groupId = System.getenv("group")
+			artifactId = 'ens-nbt'
+			version = System.getenv("version")
+
+			from components.java
+		}
+	}
 }
 
 dependencies {
-	testCompile 'junit:junit:4.12'
+	testImplementation 'junit:junit:4.13.2'
+	jmh 'org.openjdk.jmh:jmh-core:1.37'
+	jmh 'org.openjdk.jmh:jmh-generator-annprocess:1.37'
+}
+
+// Configure the JMH plugin
+jmh {
+	// Use an existing test source set for JMH benchmarks, or let the plugin create one
+	// jmh.includes is an array of regular expressions that should match against the
+	// fully qualified names of classes that contain benchmarks.
+	includes = [".*"]
+
+	warmupIterations = 5
+	iterations = 10
+	fork = 1
+
+	resultFormat = 'json'
+	resultsFile = new File('build/reports/jmh/results.json')
 }
 
 javadoc {
 	source = sourceSets.main.allJava
-	classpath = configurations.compile
 	destinationDir = file("./doc/")
-	options.windowTitle 'NBT'
+	include 'io/github/ensgijs/nbt/**'
+	options.windowTitle 'NBT (ENS)'
 	options.encoding 'UTF-8'
 	options.linkSource true
-	options.links 'https://docs.oracle.com/javase/8/docs/api/'
+	options.links 'https://docs.oracle.com/javase/17/docs/api/'
 }
 
 task sourcesJar(type: Jar, dependsOn: classes) {
-	classifier = 'sources'
+	archiveClassifier = 'sources'
 	from sourceSets.main.allSource
 }
 
 task javadocJar(type: Jar, dependsOn: javadoc) {
-	classifier = 'javadoc'
+	archiveClassifier = 'javadoc'
 	from javadoc.destinationDir
 }
 
 jacocoTestReport {
 	reports {
-		xml.enabled = true
-		html.enabled = true
+		xml.required = true
+		html.required = true
 	}
 }
 
 artifacts {
 	archives sourcesJar
 	archives javadocJar
 }
+
+java {
+	withJavadocJar()
+	withSourcesJar()
+}
+
+tasks.register('profilingRun', JavaExec) {
+	mainClass = 'io.github.ensgijs.nbt.profiler.ProfilingRunner'
+	classpath = sourceSets.main.runtimeClasspath
+	classpath += sourceSets.test.runtimeClasspath
+	classpath += sourceSets.jmh.runtimeClasspath
+
+	doFirst {
+		file('build/jfr-profiling').mkdirs()
+	}
+
+	def jfrSettingsFile = sourceSets.jmh.resources.find {it.name == 'profiler_settings.jfc'}
+	if (!jfrSettingsFile) {
+		throw new GradleException("JFR profiler_settings.jfc file not found in jmh/resources folder.")
+	}
+
+	// Add JVM arguments to enable JFR and save a recording
+	jvmArgs += [
+			"-XX:StartFlightRecording=duration=10s,filename=build/jfr-profiling/profiling-run.jfr,settings=${jfrSettingsFile.getAbsolutePath()}"
+	]
+}

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists