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