|
| 1 | +/* |
| 2 | + * Copyright (c) 2025 Splatgames.de Software and Contributors |
| 3 | + * |
| 4 | + * Permission is hereby granted, free of charge, to any person obtaining a copy |
| 5 | + * of this software and associated documentation files (the "Software"), to deal |
| 6 | + * in the Software without restriction, including without limitation the rights |
| 7 | + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 8 | + * copies of the Software, and to permit persons to whom the Software is |
| 9 | + * furnished to do so, subject to the following conditions: |
| 10 | + * |
| 11 | + * The above copyright notice and this permission notice shall be included in all |
| 12 | + * copies or substantial portions of the Software. |
| 13 | + * |
| 14 | + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 15 | + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 16 | + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 17 | + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 18 | + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 19 | + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 20 | + * SOFTWARE. |
| 21 | + */ |
| 22 | + |
| 23 | +/** |
| 24 | + * <strong>DEPRECATED:</strong> Legacy package for Jackson-based {@link de.splatgames.aether.datafixers.api.dynamic.DynamicOps} |
| 25 | + * implementation. This package is retained only for backwards compatibility and will be removed in version 1.0.0. |
| 26 | + * |
| 27 | + * <p>This package contains the original {@link de.splatgames.aether.datafixers.codec.jackson.JacksonOps} class |
| 28 | + * from the pre-0.4.0 package structure. All classes in this package are deprecated and delegate to their |
| 29 | + * replacements in the reorganized {@link de.splatgames.aether.datafixers.codec.json.jackson} package.</p> |
| 30 | + * |
| 31 | + * <h2>Migration Guide</h2> |
| 32 | + * <p>To migrate from this deprecated package to the new package structure:</p> |
| 33 | + * |
| 34 | + * <h3>Import Changes</h3> |
| 35 | + * <pre>{@code |
| 36 | + * // Old imports (deprecated, will be removed in 1.0.0) |
| 37 | + * import de.splatgames.aether.datafixers.codec.jackson.JacksonOps; |
| 38 | + * |
| 39 | + * // New imports (recommended) |
| 40 | + * import de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps; |
| 41 | + * }</pre> |
| 42 | + * |
| 43 | + * <h3>Code Changes</h3> |
| 44 | + * <p>The class has been renamed from {@code JacksonOps} to {@code JacksonJsonOps} for clarity:</p> |
| 45 | + * <pre>{@code |
| 46 | + * // Old code (deprecated) |
| 47 | + * JacksonOps ops = JacksonOps.INSTANCE; |
| 48 | + * JacksonOps customOps = new JacksonOps(customMapper); |
| 49 | + * Dynamic<JsonNode> dynamic = new Dynamic<>(ops, jsonNode); |
| 50 | + * |
| 51 | + * // New code (recommended) |
| 52 | + * JacksonJsonOps ops = JacksonJsonOps.INSTANCE; |
| 53 | + * JacksonJsonOps customOps = new JacksonJsonOps(customMapper); |
| 54 | + * Dynamic<JsonNode> dynamic = new Dynamic<>(ops, jsonNode); |
| 55 | + * }</pre> |
| 56 | + * |
| 57 | + * <h2>Deprecation Timeline</h2> |
| 58 | + * <table border="1"> |
| 59 | + * <caption>Deprecation and Removal Schedule</caption> |
| 60 | + * <tr><th>Version</th><th>Status</th><th>Action Required</th></tr> |
| 61 | + * <tr><td>0.4.0</td><td>Deprecated</td><td>Update imports and class names; old code continues to work</td></tr> |
| 62 | + * <tr><td>0.5.0 - 0.9.x</td><td>Deprecated</td><td>Warnings during compilation; functionality unchanged</td></tr> |
| 63 | + * <tr><td>1.0.0</td><td><strong>Removed</strong></td><td>Package deleted; migration required before upgrade</td></tr> |
| 64 | + * </table> |
| 65 | + * |
| 66 | + * <h2>Why This Change?</h2> |
| 67 | + * <p>The package reorganization in version 0.4.0 introduced a cleaner, more scalable structure:</p> |
| 68 | + * <ul> |
| 69 | + * <li><strong>Format-Based Organization:</strong> All JSON implementations are now grouped under |
| 70 | + * {@code codec.json.*}, YAML under {@code codec.yaml.*}, etc.</li> |
| 71 | + * <li><strong>Library-Based Subpackages:</strong> Each format has subpackages for different |
| 72 | + * libraries (e.g., {@code json.gson}, {@code json.jackson})</li> |
| 73 | + * <li><strong>Disambiguated Naming:</strong> {@code JacksonOps} is now {@code JacksonJsonOps} to |
| 74 | + * distinguish it from {@code JacksonYamlOps}, {@code JacksonTomlOps}, and {@code JacksonXmlOps}</li> |
| 75 | + * </ul> |
| 76 | + * |
| 77 | + * <h2>New Package Structure</h2> |
| 78 | + * <pre> |
| 79 | + * de.splatgames.aether.datafixers.codec |
| 80 | + * ├── json |
| 81 | + * │ ├── gson/GsonOps.java |
| 82 | + * │ └── jackson/JacksonJsonOps.java (renamed from JacksonOps) |
| 83 | + * ├── yaml |
| 84 | + * │ ├── jackson/JacksonYamlOps.java (new) |
| 85 | + * │ └── snakeyaml/SnakeYamlOps.java (new) |
| 86 | + * ├── toml |
| 87 | + * │ └── jackson/JacksonTomlOps.java (new) |
| 88 | + * └── xml |
| 89 | + * └── jackson/JacksonXmlOps.java (new) |
| 90 | + * </pre> |
| 91 | + * |
| 92 | + * <h2>Class Mapping</h2> |
| 93 | + * <table border="1"> |
| 94 | + * <caption>Old to New Class Mapping</caption> |
| 95 | + * <tr><th>Old Class (Deprecated)</th><th>New Class (Recommended)</th></tr> |
| 96 | + * <tr> |
| 97 | + * <td>{@link de.splatgames.aether.datafixers.codec.jackson.JacksonOps}</td> |
| 98 | + * <td>{@link de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps}</td> |
| 99 | + * </tr> |
| 100 | + * <tr> |
| 101 | + * <td>{@code JacksonOps.INSTANCE}</td> |
| 102 | + * <td>{@link de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps#INSTANCE}</td> |
| 103 | + * </tr> |
| 104 | + * <tr> |
| 105 | + * <td>{@code new JacksonOps(mapper)}</td> |
| 106 | + * <td>{@code new JacksonJsonOps(mapper)}</td> |
| 107 | + * </tr> |
| 108 | + * </table> |
| 109 | + * |
| 110 | + * <h2>Delegation Pattern</h2> |
| 111 | + * <p>The deprecated {@link de.splatgames.aether.datafixers.codec.jackson.JacksonOps} class uses the |
| 112 | + * delegation pattern to forward all method calls to the new |
| 113 | + * {@link de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps} implementation. This ensures:</p> |
| 114 | + * <ul> |
| 115 | + * <li>Identical behavior between deprecated and new implementations</li> |
| 116 | + * <li>Bug fixes applied to the new implementation automatically benefit deprecated users</li> |
| 117 | + * <li>No performance overhead beyond a single method delegation</li> |
| 118 | + * </ul> |
| 119 | + * |
| 120 | + * <h2>Thread Safety</h2> |
| 121 | + * <p>All classes in this deprecated package maintain the same thread-safety guarantees as their |
| 122 | + * replacements. The singleton {@link de.splatgames.aether.datafixers.codec.jackson.JacksonOps#INSTANCE} |
| 123 | + * can be safely shared across multiple threads. Custom instances created with a custom |
| 124 | + * {@link com.fasterxml.jackson.databind.ObjectMapper} are thread-safe if the provided mapper is thread-safe.</p> |
| 125 | + * |
| 126 | + * @author Erik Pförtner |
| 127 | + * @see de.splatgames.aether.datafixers.codec.json.jackson.JacksonJsonOps |
| 128 | + * @see de.splatgames.aether.datafixers.codec.json |
| 129 | + * @see de.splatgames.aether.datafixers.api.dynamic.DynamicOps |
| 130 | + * @since 0.1.0 |
| 131 | + * @deprecated Since 0.4.0. Use classes from {@link de.splatgames.aether.datafixers.codec.json.jackson} |
| 132 | + * instead. This package will be removed in version 1.0.0. |
| 133 | + */ |
| 134 | +@Deprecated(since = "0.4.0", forRemoval = true) |
| 135 | +package de.splatgames.aether.datafixers.codec.jackson; |
0 commit comments