@spec clear_primary(binary()) :: DSpace.API.Operation.JSON.t()

Removes the primary-file designation from a file bundle.

This does not delete the file or remove it from the bundle; it only clears the "primary" designation.

@spec create_bundle(
  map(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Creates a new file bundle.

A file bundle must have an item parent.

Parameters

• bundle - bundle attributes as a map. Supports "name" (defaults to "ORIGINAL") and "metadata".
• options - keyword list of options

Options

• :parent - UUID of the parent item (required)

@spec create_in_bundle(binary(), upload(), keyword()) :: DSpace.API.Operation.JSON.t()

Uploads a new file binary into a bundle.

Parameters

• bundle_uuid - UUID of the bundle the file is created in
• file - the file to upload, see upload/0
• options - keyword list of options

Options

• properties - optional properties map. Supports "name" (stored filename) and "metadata". If "name" is absent, the upload's filename is used.

Note: If the payload is passed in form of a path to a file on disk, the file will only be read from disk when the request is actually sent with DSpace.API.request/3, not when calling this function.

Examples

# From a path on disk
File.create_in_bundle(bundle_uuid, "files/test.pdf")

# From in-memory content with metadata
File.create_in_bundle(bundle_uuid, {"report.pdf", pdf_binary, "application/pdf"}, %{
  "metadata" => %{"dc.description" => [%{"value" => "Final report"}]}
})

@spec delete(
  binary() | [binary()],
  keyword()
) :: DSpace.API.Operation.JSON.t()

Deletes one or more files.

All files in a bulk delete must be attached to an item.

@spec delete_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Deletes a file bundle.

Executing this operation also deletes all files in the bundle.

@spec download(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Downloads a file binary.

This operation will pass a :decode_body option with false to the HTTP adapter, so the bytes are returned verbatim regardless of the file's content type.

Restricted files require a short-lived authentication token passed as an option (see DSpace.API.Auth.fetch_short_lived_token/0).

Streaming to disk

Req supports streaming the response body straight to disk which is useful especially for large files. If you use a Req-based HTTP adapter (which is this library's default), passing :into as an override option to DSpace.API.request/3 will stream the body to disk:

uuid
|> File.download()
|> DSpace.API.request(client, into: File.stream!("myfile.pdf"))

Options

• :auth_token - short-lived token granting access to a restricted file

@spec fetch(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Fetches a single file by UUID.

@spec fetch_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Fetches a file bundle by UUID.

@spec fetch_by_item_handle(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Fetches a single file via its parent item's handle.

Either :sequence or :file_name option must be given.

Options

• :sequence - the file's sequence id as an integer
• :file_name - the file's name as a string

@spec fetch_primary_from_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the primary file of a file bundle.

@spec find_by_item(binary(), binary(), keyword()) :: DSpace.API.Operation.JSON.t()

Finds the files of an item within a bundle.

This operation can be streamed.

Parameters

• item_uuid - UUID of the item
• bundle_name - name of the bundle (e.g. "ORIGINAL")
• options - keyword list of options

Options

• :filters - list of {metadata_field, value} tuples to filter by
• :exclude_hidden - when true, excludes files flagged with the bitstream.hide metadata (default: false)
• :page - Page number (0-based)
• :size - Items per page

@spec format(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the format of a file.

@spec list(keyword()) :: DSpace.API.Operation.JSON.t()

Lists files within a bundle.

The main "bitstreams" endpoint is not browsable, so listing is always bundle-scoped. Equivalent to list_in_bundle/2.

This operation can be streamed.

Options

• :bundle - Required. UUID of the bundle to list files from
• :page - Page number (0-based)
• :size - Items per page

@spec list_in_bundle(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Lists the files within a bundle.

This operation can be streamed.

## Options

• :page - Page number (0-based)
• :size - Items per page

@spec make_primary(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Makes the file the primary file of a bundle.

Executing this operation changes the primary file of a bundle that already has one. Use set_primary/2 when the bundle has no primary file yet.

@spec move(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Moves a file to another bundle.

@spec reorder(binary(), [map()]) :: DSpace.API.Operation.JSON.t()

Reorders the files within a bundle.

Takes the raw list of move operations, e.g. to move the file at index 1 to the front:

File.reorder(bundle_uuid, [
  %{
    "op" => "move",
    "from" => "/_links/bitstreams/1/href",
    "path" => "/_links/bitstreams/0/href"
  }
])

@spec set_format(binary(), integer() | binary()) :: DSpace.API.Operation.JSON.t()

Assigns a registered format to a file.

Parameters

• uuid - the UUID of the file
• format_id - the integer id of a format in the "format registry" (see DSpace.API.File.FormatRegistry).

@spec set_primary(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Sets the file as the primary file of a bundle.

Use this when the bundle has no primary file yet; use make_primary/2 to change an existing one.

@spec thumbnail(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the thumbnail of a file.

Note: Thumbnails are usually only available for files in the ORIGINAL bundle.

@spec update(binary(), [DSpace.API.Operation.JSON.t()], keyword()) ::
  DSpace.API.Operation.JSON.t()

Updates a file's metadata.

@spec upload(
  upload(),
  keyword()
) :: DSpace.API.Operation.t()

Uploads a file to an item.

A file must always be created inside a "bundle", so adding a file to an item is really two API requests: (1) create the target bundle with create_bundle/2, then (2) create_in_bundle/3 the file into it. Executing this operation chains both steps: it creates a bundle on the parent item and then creates the file inside it, returning the created file.

Parameters

• file - the file to upload, see upload/0
• options - keyword list of options

Options

• :parent - UUID of the parent item (required)
• :bundle - optional bundle attributes map, see create_bundle/2
• :properties - optional file properties map, see create_in_bundle/3

Examples

File.upload("files/test.pdf", parent: item_uuid)

File.upload({"report.pdf", pdf_binary, "application/pdf"},
  parent: item_uuid,
  bundle: %{"name" => "ORIGINAL"},
  properties: %{"metadata" => %{"dc.description" => [%{"value" => "Final report"}]}}
)