Wiki source code of Blob Store API
Last modified by Michael Hamann on 2026/02/05 17:22
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Every feature that stores data permanently that isn't suitable for the database or Solr should store data in a blob store. Depending on the configuration, this data will be stored in the file system, on S3, or another storage solution (the system is extensible). The blob store can be obtained by injecting an ##org.xwiki.store.blob.BlobStoreManager## component and getting the blob store using its ###getBlobStore## method. Each blob store needs a name which corresponds to the subdirectory in the permanent store with the file system or the key prefix in S3. It is possible to use ##/## in the name for choosing a subdirectory. Apart from ##/## for subdirectories, ##-## and ##_##, no special characters should be used in blob store names. | ||
| 2 | |||
| 3 | While blob store instances are cached, it is recommended that ##BlobStore## instances obtained from ##BlobStoreManager## are, e.g., requested once during component initialization and then stored in a member variable. | ||
| 4 | |||
| 5 | == Blob Paths == | ||
| 6 | |||
| 7 | Each blob is referenced by a ##BlobPath##. This path describes the absolute location of a blob inside a blob store. To provide an API that is familiar to developers, its API is heavily inspired by ##java.nio.file.Path##. Similar to the ##Path## API, a blob path can be either absolute or relative. However, a blob path is always fully normalized, there will never be any segments named ##.## in a blob path and ##..## segments may only occur at the start of a relative path. Absolute paths need to be fully normalized at construction time while relative paths are normalized internally. This helps to avoid surprises when constructing absolute paths while still offering the full flexibility with relative paths. | ||
| 8 | |||
| 9 | === Constructing Blob Paths === | ||
| 10 | |||
| 11 | The following static methods are available for constructing blob paths: | ||
| 12 | |||
| 13 | |=Name|=Description | ||
| 14 | |##root()##|Provides the root path (##/##) | ||
| 15 | |##absolute(String... names)##|Constructs an absolute blob path from the given path segments (can be empty). Dot-segments are forbidden. | ||
| 16 | |##absolute(Iterable<String> names)##|Constructs an absolute blob path from the given path segments (can be empty). Dot-segments are forbidden. | ||
| 17 | |##relative(String... names)##|Constructs a relative blob path from the given path segments (can be empty). Dot-segments are allowed and will be normalized. | ||
| 18 | |##relative(Iterable<String> names)##|Constructs a relative blob path from the given path segments (can be empty). Dot-segments are allowed and will be normalized. | ||
| 19 | |##parse(CharSequence path)##|Parses the given relative or absolute path. If the path starts with "##/##", dot-segments are forbidden, otherwise they're normalized. | ||
| 20 | |||
| 21 | == Blob Store Operations == | ||
| 22 | |||
| 23 | See [[BlobStore.java>>https://github.com/xwiki/xwiki-commons/blob/c77d88e07480bebe733aacea79e639a5f1b6ba8e/xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/BlobStore.java#L33]]. | ||
| 24 | |||
| 25 | === Blob Operations === | ||
| 26 | |||
| 27 | See [[Blob.java>>https://github.com/xwiki/xwiki-commons/blob/c77d88e07480bebe733aacea79e639a5f1b6ba8e/xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/Blob.java#L35]]. |
