Package io.ocfl.core

Class OcflRepositoryBuilder

java.lang.Object
io.ocfl.core.OcflRepositoryBuilder
public class OcflRepositoryBuilder extends Object
Constructs a local file system based OCFL repository sensible defaults that can be overridden prior to calling build().

Important: The same OcflRepositoryBuilder instance MUST NOT be used to initialize multiple repositories.

  • Constructor Details

    • OcflRepositoryBuilder

      public OcflRepositoryBuilder()
      Constructs a local file system based OCFL repository sensible defaults that can be overridden prior to calling build().

      Important: The same OcflRepositoryBuilder instance MUST NOT be used to initialize multiple repositories.

  • Method Details

    • storage

      public OcflRepositoryBuilder storage(OcflStorage storage)
      The storage layer the repository should use. Required.
      Parameters:
      storage - the storage layer implementation that the OCFL repository should use
      Returns:
      builder

    • storage

      public OcflRepositoryBuilder storage(Consumer<OcflStorageBuilder> configureStorage)
      Configure the storage layer the repository should use. Required.
      Parameters:
      configureStorage - storage configurer
      Returns:
      builder

    • workDir

      public OcflRepositoryBuilder workDir(Path workDir)
      The temporary workspace the repository uses to assemble object versions. This directory cannot be located within the OCFL storage root. Required.
      Parameters:
      workDir - the work directory to assemble versions in before they're moved to storage -- cannot be within the OCFL storage root
      Returns:
      builder

    • objectLock

      public OcflRepositoryBuilder objectLock(ObjectLock objectLock)
      Used to lock objects when writing. The default is an InMemoryObjectLock instance that will wait 10 seconds for the lock before failing. Override to change the wait period or implement a different type of lock.

      Use ObjectLockBuilder to construct an object lock that's backed by a relational database. This is primarily intended to be used when working with a cloud object store like S3.

      Parameters:
      objectLock - object lock
      Returns:
      builder
      See Also:

    • objectLock

      public OcflRepositoryBuilder objectLock(Consumer<ObjectLockBuilder> configureLock)
      Configures the object lock that's used. The default is an InMemoryObjectLock instance that will wait 10 seconds for the lock before failing. Set the DataSource on the builder if you'd like to use a DB lock instead.
      Parameters:
      configureLock - use to configure the lock
      Returns:
      builder
      See Also:

    • inventoryCache

      public OcflRepositoryBuilder inventoryCache(Cache<String,Inventory> inventoryCache)
      Used to cache deserialized inventories. The default is an in memory CaffeineCache instance that has a maximum size of 1,000 objects and an expiry of 10 minutes. Override to adjust the settings or change the cache implementation.
      Parameters:
      inventoryCache - inventory cache
      Returns:
      builder

    • objectDetailsDb

      public OcflRepositoryBuilder objectDetailsDb(ObjectDetailsDatabase objectDetailsDb)
      Used to store details about OCFL objects in the repository. This is primarily intended to be used when working with a cloud object store like S3. Use ObjectDetailsDatabaseBuilder to construct an ObjectDetailsDatabase instance.
      Parameters:
      objectDetailsDb - object details db
      Returns:
      builder
      See Also:

    • objectDetailsDb

      public OcflRepositoryBuilder objectDetailsDb(Consumer<ObjectDetailsDatabaseBuilder> configureDb)
      Used to store details about OCFL objects in the repository. This is primarily intended to be used when working with a cloud object store like S3.
      Parameters:
      configureDb - use to configure the object details db
      Returns:
      builder
      See Also:

    • prettyPrintJson

      public OcflRepositoryBuilder prettyPrintJson()
      Changes the InventoryMapper to pretty print Inventory JSON files so that they are human readable but use more disk space.
      Returns:
      builder

    • inventoryMapper

      public OcflRepositoryBuilder inventoryMapper(InventoryMapper inventoryMapper)
      Used to override the default InventoryMapper, which is used to serialize Inventories to JSON files. The default mapper will emit as little whitespace as possible.
      Parameters:
      inventoryMapper - inventory serializer
      Returns:
      builder

    • logicalPathMapper

      public OcflRepositoryBuilder logicalPathMapper(LogicalPathMapper logicalPathMapper)
      Overrides the default DirectLogicalPathMapper. LogicalPathMappers are used to map logical paths to content paths so that they can safely be written to disk. The default behaviour is to map logical paths to content paths directly without any changes.
      Parameters:
      logicalPathMapper - logical path mapper
      Returns:
      builder
      See Also:

    • contentPathConstraints

      public OcflRepositoryBuilder contentPathConstraints(ContentPathConstraintProcessor contentPathConstraints)
      Overrides the default ContentPathConstraintProcessor that is used to enforce restrictions on what constitutes a valid content path. By default, there are no restrictions.

      Path constraints are applied after logical paths are mapped to content paths, and are used to attempt to ensure the portability of content paths. The following default generic constraint configurations are provided:

      Constraints should be applied that target filesystems that are NOT the local filesystem. The local filesystem will enforce its own constraints just fine. This mechanism is intended to enforce path constraints that the local filesystem does not.

      If you use the builtin constraint processor, the following constraints are ALWAYS applied:

      • Cannot have a leading OR trailing /
      • Cannot contain the following filenames: '.', '..'
      • Cannot contain an empty filename
      • Windows only: Cannot contain a \
      Parameters:
      contentPathConstraints - constraint processor
      Returns:
      builder
      See Also:

    • ocflConfig

      public OcflRepositoryBuilder ocflConfig(OcflConfig config)
      Sets OCFL configuration options.
      Parameters:
      config - OCFL config
      Returns:
      builder

    • ocflConfig

      public OcflRepositoryBuilder ocflConfig(Consumer<OcflConfig> configureConfig)
      Sets OCFL configuration options.
      Parameters:
      configureConfig - configures the OCFL config
      Returns:
      builder

    • defaultLayoutConfig

      public OcflRepositoryBuilder defaultLayoutConfig(OcflExtensionConfig defaultLayoutConfig)
      Sets the default OCFL storage layout configuration. A layout MUST be specified if the OCFL repository does not yet exist. If the repository does exist and it has a storage layout defined, then a layout does not need to be specified and, if it is specified here, it will be ignored.
      Parameters:
      defaultLayoutConfig - the default storage layout configuration
      Returns:
      builder
      See Also:

    • unsupportedExtensionBehavior

      public OcflRepositoryBuilder unsupportedExtensionBehavior(UnsupportedExtensionBehavior unsupportedBehavior)
      Set the behavior when an unsupported extension is encountered. By default, ocfl-java will not operate on repositories or objects that contain unsupported extensions. Set this value to WARN, if you'd like ocfl-java to log a WARNing, but continue to operate instead.

      Specific unsupported extensions may be ignored individually using ignoreUnsupportedExtensions

      Parameters:
      unsupportedBehavior - FAIL to throw an exception or WARN to log a warning
      Returns:
      builder

    • ignoreUnsupportedExtensions

      public OcflRepositoryBuilder ignoreUnsupportedExtensions(Set<String> ignoreUnsupportedExtensions)
      Sets a list of unsupported extensions that should be ignored. If the unsupported extension behavior is set to FAIL, this means that these extensions will produce log WARNings if they are encountered. If the behavior is set to WARN, then these extensions will be silently ignored.
      Parameters:
      ignoreUnsupportedExtensions - set of unsupported extension names that should be ignored
      Returns:
      builder

    • verifyStaging

      public OcflRepositoryBuilder verifyStaging(boolean verifyStaging)
      Configures whether to verify the contents of a staged version before it is moved into the OCFL object. This verification includes iterating over all of the files in the version and ensuring they match the expectations in the inventory.

      This verification is enabled by default out of conservatism. It is unlikely that there will ever be a problem for it to uncover, and it can be safely disabled if there are concerns about performance on slower filesystems.

      Parameters:
      verifyStaging - true if the contents of a stage version should be double-checked
      Returns:
      builder

    • fileLockTimeoutDuration

      public OcflRepositoryBuilder fileLockTimeoutDuration(Duration fileLockTimeoutDuration)
      Configures the max amount of time to wait for a file lock when updating an object from multiple threads. This only matters if you concurrently write files to the same object, and can otherwise be ignored. The default timeout is 1 minute.
      Parameters:
      fileLockTimeoutDuration - the max amount of time to wait for a file lock
      Returns:
      builder

    • build

      public OcflRepository build()
      Constructs an OCFL repository. Brand new repositories are initialized.

      Remember to call OcflRepository.close() when you are done with the repository.

      Returns:
      OcflRepository

    • buildMutable

      public MutableOcflRepository buildMutable()
      Constructs an OCFL repository that allows the use of the Mutable HEAD Extension. Brand new repositories are initialized.

      Remember to call OcflRepository.close() when you are done with the repository.

      Returns:
      MutableOcflRepository