Matthias Andreas Benkard | b5d657a | 2022-02-03 21:14:30 +0100 | [diff] [blame^] | 1 | // SPDX-FileCopyrightText: © 2021 Matthias Andreas Benkard <code@mail.matthias.benkard.de> |
| 2 | // |
| 3 | // SPDX-License-Identifier: LGPL-3.0-or-later |
| 4 | |
Matthias Andreas Benkard | 4e8423d | 2021-12-19 22:56:09 +0100 | [diff] [blame] | 5 | /** |
| 6 | * Provides record classes describing the elements of <a |
| 7 | * href="https://ostreedev.github.io/ostree/">OSTree</a> repositories and factory methods to create |
| 8 | * {@link eu.mulk.jgvariant.core.Decoder} instances for them. |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 9 | * |
| 10 | * <h2>OStree repository structure</h2> |
| 11 | * |
| 12 | * <p>An OSTree repository has the following layout: |
| 13 | * |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 14 | * <dl> |
| 15 | * <dt>{@code config} |
| 16 | * <dd> |
| 17 | * <p>A plain text file that contains various settings. Among other things, this defines the |
| 18 | * <a href="https://ostreedev.github.io/ostree/formats/#the-archive-format">archive format</a> |
| 19 | * of the repository and whether files are compressed ({@code mode=archive-z2}) or plain |
| 20 | * ({@code mode=bare}, {@code mode=bare-user}). |
| 21 | * <dt>{@code summary} |
| 22 | * <dd> |
| 23 | * <p>A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is |
| 24 | * available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}. |
| 25 | * <p>This file may or may not exist and, if it exists, may or may not be up to date. |
| 26 | * <dt>{@code refs/heads{/name...}} |
| 27 | * <dd> |
| 28 | * <p>Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format |
| 29 | * (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to {@link |
| 30 | * eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the {@code objects/} |
| 31 | * directory that this refers to. |
| 32 | * <dt>{@code objects/{ξ₀ξ₁}/{ξ₂ξ₃ξ₄ξ₅...}.{ext}} |
| 33 | * <dd> |
| 34 | * <p>Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} and |
| 35 | * keyed by {@link eu.mulk.jgvariant.ostree.Checksum}. |
| 36 | * <p>Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit} |
| 37 | * ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), and {@link |
| 38 | * eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as plain ({@code |
| 39 | * .file}) or compressed files ({@code .filez}). |
| 40 | * <p>Static delta information is not stored here, but in the {@code deltas/} and {@code |
| 41 | * delta-indexes/} directories (if available). |
| 42 | * <p>The individual parts of the file path are defined as follows: |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 43 | * <dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 44 | * <dt>{@code {ξ₀ξ₁}} |
| 45 | * <dd>the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} |
| 46 | * <dt>{@code {ξ₂ξ₃ξ₄ξ₅...}} |
| 47 | * <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the |
| 48 | * 3rd character |
| 49 | * <dt>{@code {ext}} |
| 50 | * <dd>the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 51 | * </dl> |
Matthias Andreas Benkard | b5d657a | 2022-02-03 21:14:30 +0100 | [diff] [blame^] | 52 | * <dt id="delta-superblock">{@code objects/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}.{ext}}/superblock |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 53 | * <dd> |
| 54 | * <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit) |
| 55 | * to the commit named by the checksum encoded in the path. |
| 56 | * <p>The individual parts of the file path are defined as follows: |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 57 | * <dl> |
Matthias Andreas Benkard | b5d657a | 2022-02-03 21:14:30 +0100 | [diff] [blame^] | 58 | * <dt>{@code {ν₀ν₁}} |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 59 | * <dd>the first two characters of {@link |
| 60 | * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta |
| 61 | * ends at |
Matthias Andreas Benkard | b5d657a | 2022-02-03 21:14:30 +0100 | [diff] [blame^] | 62 | * <dt>{@code {ν₂ν₃ν₄ν₅...}} |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 63 | * <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the |
| 64 | * target commit the delta ends at starting from the 3rd character |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 65 | * </dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 66 | * <dt>{@code deltas/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}/{digit...}} |
| 67 | * <dd> |
| 68 | * <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from |
| 69 | * nothing (an empty commit) to the commit named by the checksum encoded in the path. |
| 70 | * <p>The individual parts of the file path are defined as follows: |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 71 | * <dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 72 | * <dt>{@code {ν₀ν₁}} |
| 73 | * <dd>the first two characters of {@link |
| 74 | * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta |
| 75 | * ends at |
| 76 | * <dt>{@code {ν₂ν₃ν₄ν₅...}} |
| 77 | * <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the |
| 78 | * target commit the delta ends at starting from the 3rd character |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 79 | * </dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 80 | * <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/superblock} |
| 81 | * <dd> |
| 82 | * <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit |
| 83 | * referenced by the first checksum encoded in the path to the target commit referenced in the |
| 84 | * second checksum encoded in the path. |
| 85 | * <p>The individual parts of the file path are defined as follows: |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 86 | * <dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 87 | * <dt>{@code {μ₀μ₁}} |
| 88 | * <dd>the first two characters of {@link |
| 89 | * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta |
| 90 | * starts from |
| 91 | * <dt>{@code {μ₂μ₃μ₄μ₅...}} |
| 92 | * <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the |
| 93 | * source commit the delta starts from starting from the 3rd character |
| 94 | * <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}} |
| 95 | * <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target |
| 96 | * commit the delta ends at |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 97 | * </dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 98 | * <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/{digit...}} |
| 99 | * <dd> |
| 100 | * <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from |
| 101 | * the source commit referenced by the first checksum encoded in the path to the target commit |
| 102 | * referenced in the second checksum encoded in the path. |
| 103 | * <p>The individual parts of the file path are defined as follows: |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 104 | * <dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 105 | * <dt>{@code {μ₀μ₁}} |
| 106 | * <dd>the first two characters of {@link |
| 107 | * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta |
| 108 | * starts from |
| 109 | * <dt>{@code {μ₂μ₃μ₄μ₅...}} |
| 110 | * <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the |
| 111 | * source commit the delta starts from starting from the 3rd character |
| 112 | * <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}} |
| 113 | * <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target |
| 114 | * commit the delta ends at |
Matthias Andreas Benkard | c7aa2b6 | 2022-01-23 18:10:03 +0100 | [diff] [blame] | 115 | * </dl> |
Matthias Andreas Benkard | 33d9ffa | 2022-01-25 07:52:44 +0100 | [diff] [blame] | 116 | * </dl> |
Matthias Andreas Benkard | 4e8423d | 2021-12-19 22:56:09 +0100 | [diff] [blame] | 117 | */ |
| 118 | @API(status = Status.EXPERIMENTAL) |
| 119 | package eu.mulk.jgvariant.ostree; |
| 120 | |
| 121 | import org.apiguardian.api.API; |
| 122 | import org.apiguardian.api.API.Status; |