| 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 | * |
| 10 | * <table> |
| 11 | * <caption>OSTree repository layout</caption> |
| 12 | * |
| 13 | * <tr> |
| 14 | * <td>{@code config}</td> |
| 15 | * <td> |
| 16 | * <p> |
| 17 | * A plain text file that contains various settings. Among other things, this defines |
| 18 | * the <a href="https://ostreedev.github.io/ostree/formats/#the-archive-format">archive |
| 19 | * format</a> of the repository and whether files are compressed ({@code mode=archive-z2}) |
| 20 | * or plain ({@code mode=bare}, {@code mode=bare-user}). |
| 21 | * </p> |
| 22 | * </td> |
| 23 | * </tr> |
| 24 | * |
| 25 | * <tr> |
| 26 | * <td>{@code summary}</td> |
| 27 | * <td> |
| 28 | * <p> |
| 29 | * A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is |
| 30 | * available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}. |
| 31 | * </p> |
| 32 | * |
| 33 | * <p>This file may or may not exist and, if it exists, may or may not be up to date.</p> |
| 34 | * </td> |
| 35 | * </tr> |
| 36 | * |
| 37 | * <tr> |
| 38 | * <td>{@code refs/heads/{name...}}</td> |
| 39 | * <td>Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format |
| 40 | * (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to |
| 41 | * {@link eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the |
| 42 | * {@code objects/} directory that this refers to.</td> |
| 43 | * </tr> |
| 44 | * |
| 45 | * <tr> |
| 46 | * <td>{@code objects/{checksumHead}/{checksumRest}.{fileExtension}}</td> |
| 47 | * <td> |
| 48 | * <p> |
| 49 | * Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} |
| 50 | * and keyed by {@link eu.mulk.jgvariant.ostree.Checksum}. |
| 51 | * </p> |
| 52 | * |
| 53 | * <p> |
| 54 | * Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit} |
| 55 | * ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), |
| 56 | * and {@link eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as |
| 57 | * plain ({@code .file}) or compressed files ({@code .filez}). |
| 58 | * </p> |
| 59 | * |
| 60 | * <p> |
| 61 | * Static delta information is not stored here, but in the {@code deltas/} and |
| 62 | * {@code delta-indexes/} directories (if available). |
| 63 | * </p> |
| 64 | * |
| 65 | * <p> |
| 66 | * The individual parts of the file path are defined as follows: |
| 67 | * </p> |
| 68 | * |
| 69 | * <dl> |
| 70 | * <dt>{@code {checksumHead}} |
| 71 | * <dd> |
| 72 | * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} |
| 73 | * <dt>{@code {checksumRest}} |
| 74 | * <dd> |
| 75 | * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the |
| 76 | * 3rd character |
| 77 | * <dt>{@code {fileExtension}} |
| 78 | * <dd> |
| 79 | * the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type |
| 80 | * </dl> |
| 81 | * </td> |
| 82 | * </tr> |
| 83 | * |
| 84 | * <tr id="delta-superblock"> |
| 85 | * <td>{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/superblock}</td> |
| 86 | * <td> |
| 87 | * <p> |
| 88 | * A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit) |
| 89 | * to the commit named by the checksum encoded in the path. |
| 90 | * </p> |
| 91 | * |
| 92 | * <p> |
| 93 | * The individual parts of the file path are defined as follows: |
| 94 | * </p> |
| 95 | * |
| 96 | * <dl> |
| 97 | * <dt>{@code {checksumHead}} |
| 98 | * <dd> |
| 99 | * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} |
| 100 | * <dt>{@code {checksumRest}} |
| 101 | * <dd> |
| 102 | * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting |
| 103 | * from the 3rd character |
| 104 | * </dl> |
| 105 | * </td> |
| 106 | * </tr> |
| 107 | * |
| 108 | * <tr> |
| 109 | * <td>{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/{digit...}}</td> |
| 110 | * <td> |
| 111 | * <p> |
| 112 | * A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from |
| 113 | * nothing (an empty commit) to the commit named by the checksum encoded in the path. |
| 114 | * </p> |
| 115 | * |
| 116 | * <p> |
| 117 | * The individual parts of the file path are defined as follows: |
| 118 | * </p> |
| 119 | * |
| 120 | * <dl> |
| 121 | * <dt>{@code {checksumHead}} |
| 122 | * <dd> |
| 123 | * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} |
| 124 | * <dt>{@code {checksumRest}} |
| 125 | * <dd> |
| 126 | * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting |
| 127 | * from the 3rd character |
| 128 | * </dl> |
| 129 | * </td> |
| 130 | * </tr> |
| 131 | * |
| 132 | * <tr> |
| 133 | * <td>{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/superblock}</td> |
| 134 | * <td> |
| 135 | * <p> |
| 136 | * A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit |
| 137 | * referenced by the first checksum encoded in the path to the target commit referenced |
| 138 | * in the second checksum encoded in the path. |
| 139 | * </p> |
| 140 | * |
| 141 | * <p> |
| 142 | * The individual parts of the file path are defined as follows: |
| 143 | * </p> |
| 144 | * |
| 145 | * <dl> |
| 146 | * <dt>{@code {checksumHead}} |
| 147 | * <dd> |
| 148 | * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} |
| 149 | * <dt>{@code {checksumRest}} |
| 150 | * <dd> |
| 151 | * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting |
| 152 | * from the 3rd character |
| 153 | * </dl> |
| 154 | * </td> |
| 155 | * </tr> |
| 156 | * |
| 157 | * <tr> |
| 158 | * <td>{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/{digit...}}</td> |
| 159 | * <td> |
| 160 | * <p> |
| 161 | * A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from |
| 162 | * the source commit referenced by the first checksum encoded in the path to the target |
| 163 | * commit referenced in the second checksum encoded in the path. |
| 164 | * </p> |
| 165 | * |
| 166 | * <p> |
| 167 | * The individual parts of the file path are defined as follows: |
| 168 | * </p> |
| 169 | * |
| 170 | * <dl> |
| 171 | * <dt>{@code {checksumHead}} |
| 172 | * <dd> |
| 173 | * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} |
| 174 | * <dt>{@code {checksumRest}} |
| 175 | * <dd> |
| 176 | * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting |
| 177 | * from the 3rd character |
| 178 | * </dl> |
| 179 | * </td> |
| 180 | * </tr> |
| 181 | * </table> |
| Matthias Andreas Benkard | 4e8423d | 2021-12-19 22:56:09 +0100 | [diff] [blame] | 182 | */ |
| 183 | @API(status = Status.EXPERIMENTAL) |
| 184 | package eu.mulk.jgvariant.ostree; |
| 185 | |
| 186 | import org.apiguardian.api.API; |
| 187 | import org.apiguardian.api.API.Status; |