Package org.projectnessie.api.v2

Interface TreeApi

  • All Known Subinterfaces:
    HttpTreeApi
    public interface TreeApi
    Interface for working with "trees", that is with collections of contents at a particular point in the change history, organized in trees by their respective namespaces.

    A tree is identified by a reference (branch, tag or a "detached" commit hash).

    Only branches and tags can be created / deleted / assigned via respective "*Reference" methods. Commits cannot be deleted and get created via commit / merge / transplant operations.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      SingleReferenceResponse assignReference​(Reference.ReferenceType type, @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String reference, @Valid @NotNull Reference assignTo)
      Update a reference's HEAD to point to a different commit.
      CommitResponse commitMultipleOperations​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch, @Valid @NotNull Operations operations)
      Commit multiple operations against the given branch expecting that branch to have the given hash as its latest commit.
      SingleReferenceResponse createReference​(@Valid @NotNull @Pattern(regexp="^[A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\'") java.lang.String name, Reference.ReferenceType type, @Valid Reference sourceRef)
      Create a new reference.
      SingleReferenceResponse deleteReference​(Reference.ReferenceType type, @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String reference)
      Delete a named reference.
      ReferencesResponse getAllReferences​(ReferencesParams params)
      Get all references.
      LogResponse getCommitLog​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref, @Valid @NotNull CommitLogParams params)
      Retrieve the commit log for a ref, potentially truncated by the backend.
      ContentResponse getContent​(@Valid ContentKey key, @Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref)
      This operation returns the Content for a ContentKey in a named-reference (a Branch or Tag).
      DiffResponse getDiff​(@Valid @NotNull DiffParams params)
      Returns a set of content differences between two given references.
      EntriesResponse getEntries​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String refName, @Valid @NotNull EntriesParams params)
      Retrieve objects for a ref, potentially truncated by the backend.
      GetMultipleContentsResponse getMultipleContents​(@Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref, @Valid @NotNull GetMultipleContentsRequest request)
      Similar to getContent(ContentKey, String), but takes multiple ContentKeys and returns the Content for the one or more ContentKeys in a named-reference (a Branch or Tag).
      SingleReferenceResponse getReferenceByName​(@Valid @NotNull GetReferenceParams params)
      Get details of a particular ref, if it exists.
      MergeResponse mergeRefIntoBranch​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch, @Valid @NotNull Merge merge)
      Merge commits from any reference onto a branch.
      MergeResponse transplantCommitsIntoBranch​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch, @Valid Transplant transplant)
      Cherry-pick a set of commits into a branch.

    • Method Detail

      • createReference

        SingleReferenceResponse createReference​(@Valid @NotNull @Pattern(regexp="^[A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\'")
                                        @Valid @NotNull @Pattern(regexp="^[A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\'") java.lang.String name,
                                        @Valid @NotNull
                                        Reference.ReferenceType type,
                                        @Valid @Nullable
                                        @Valid Reference sourceRef)
                                 throws NessieNotFoundException,
                                        NessieConflictException
        Create a new reference.

        The type of reference, which can be either a Branch or Tag, determines the type of the reference to be created.

        Reference.getName() defines the name of the reference to be created, Reference.getHash() is the hash of the created reference, the HEAD of the created reference. sourceRefName is the name of the reference which contains Reference.getHash(), and must be present if Reference.getHash() is present.

        Specifying no Reference.getHash() means that the new reference will be created "at the beginning of time".

        Throws:
        NessieNotFoundException
        NessieConflictException

      • getEntries

        EntriesResponse getEntries​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                           @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String refName,
                           @Valid @NotNull
                           @Valid @NotNull EntriesParams params)
                    throws NessieNotFoundException
        Retrieve objects for a ref, potentially truncated by the backend.

        Retrieves up to maxRecords objects for the given named reference (tag or branch). The backend may respect the given max records hint, but return less or more entries. Backends may also cap the returned entries at a hard-coded limit, the default REST server implementation has such a hard-coded limit.

        Invoking getEntries() does not guarantee to return all commit log entries of a given reference, because the result can be truncated by the backend.

        To implement paging, check EntriesResponse.isHasMore() and, if true, pass the value of EntriesResponse.getToken() in the next invocation of getEntries() as the pageToken parameter.

        See org.projectnessie.client.StreamingUtil in nessie-client.

        Throws:
        NessieNotFoundException

      • getCommitLog

        LogResponse getCommitLog​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                         @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref,
                         @Valid @NotNull
                         @Valid @NotNull CommitLogParams params)
                  throws NessieNotFoundException
        Retrieve the commit log for a ref, potentially truncated by the backend.

        Retrieves up to maxRecords commit-log-entries starting at the HEAD of the given named reference (tag or branch). The backend may respect the given max records hint, but return less or more entries. Backends may also cap the returned entries at a hard-coded limit, the default REST server implementation has such a hard-coded limit.

        Invoking getCommitLog() does not guarantee to return all commit log entries of a given reference, because the result can be truncated by the backend.

        To implement paging, check LogResponse.isHasMore() and, if true, pass the value of LogResponse.getToken() in the next invocation of getCommitLog() as the pageToken parameter.

        See org.projectnessie.client.StreamingUtil in nessie-client.

        Throws:
        NessieNotFoundException

      • assignReference

        SingleReferenceResponse assignReference​(@Valid
                                        Reference.ReferenceType type,
                                        @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                        @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String reference,
                                        @Valid @NotNull
                                        @Valid @NotNull Reference assignTo)
                                 throws NessieNotFoundException,
                                        NessieConflictException
        Update a reference's HEAD to point to a different commit.
        Parameters:
        type - Optional expected type of reference being assigned. Will be validated if present.
        Throws:
        NessieNotFoundException
        NessieConflictException

      • deleteReference

        SingleReferenceResponse deleteReference​(@Valid
                                        Reference.ReferenceType type,
                                        @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                        @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String reference)
                                 throws NessieConflictException,
                                        NessieNotFoundException
        Delete a named reference.
        Parameters:
        type - Optional expected type of reference being deleted. Will be validated if present.
        Throws:
        NessieConflictException
        NessieNotFoundException

      • transplantCommitsIntoBranch

        MergeResponse transplantCommitsIntoBranch​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                          @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch,
                                          @Valid
                                          @Valid Transplant transplant)
                                   throws NessieNotFoundException,
                                          NessieConflictException
        Cherry-pick a set of commits into a branch.
        Throws:
        NessieNotFoundException
        NessieConflictException

      • mergeRefIntoBranch

        MergeResponse mergeRefIntoBranch​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                 @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch,
                                 @Valid @NotNull
                                 @Valid @NotNull Merge merge)
                          throws NessieNotFoundException,
                                 NessieConflictException
        Merge commits from any reference onto a branch.
        Throws:
        NessieNotFoundException
        NessieConflictException

      • commitMultipleOperations

        CommitResponse commitMultipleOperations​(@Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                        @Valid @NotNull @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String branch,
                                        @Valid @NotNull
                                        @Valid @NotNull Operations operations)
                                 throws NessieNotFoundException,
                                        NessieConflictException
        Commit multiple operations against the given branch expecting that branch to have the given hash as its latest commit. The hash in the successful response contains the hash of the commit that contains the operations of the invocation.
        Parameters:
        branch - Branch to change, defaults to default branch.
        operations - Operations to apply
        Returns:
        updated Branch objects with the hash of the new HEAD
        Throws:
        NessieNotFoundException - if branchName could not be found
        NessieConflictException - if the operations could not be applied to some conflict, which is either caused by a conflicting commit or concurrent commits.

      • getContent

        ContentResponse getContent​(@Valid
                           @Valid ContentKey key,
                           @Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                           @Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref)
                    throws NessieNotFoundException
        This operation returns the Content for a ContentKey in a named-reference (a Branch or Tag).

        If the table-metadata is tracked globally (Iceberg), Nessie returns a Content object, that contains the most up-to-date part for the globally tracked part (Iceberg: table-metadata) plus the per-Nessie-reference/hash specific part (Iceberg: snapshot-ID, schema-ID, partition-spec-ID, default-sort-order-ID).

        Parameters:
        key - the ContentKeys to retrieve
        ref - named-reference to retrieve the content for
        Returns:
        list of GetMultipleContentsResponse.ContentWithKeys
        Throws:
        NessieNotFoundException - if ref or hashOnRef does not exist

      • getMultipleContents

        GetMultipleContentsResponse getMultipleContents​(@Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes")
                                                @Valid @Pattern(regexp="^([A-Za-z](((?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?(@([0-9a-fA-F]{8,64})?)?|@[0-9a-fA-F]{8,64})|-$",message="Reference name must start with a letter, followed by letters, digits, one of the ./_- characters, not end with a slash or dot, not contain \'..\', optionally followed by @ and a commit hash, which must consist of the hex representation of 4-32 bytes") java.lang.String ref,
                                                @Valid @NotNull
                                                @Valid @NotNull GetMultipleContentsRequest request)
                                         throws NessieNotFoundException
        Similar to getContent(ContentKey, String), but takes multiple ContentKeys and returns the Content for the one or more ContentKeys in a named-reference (a Branch or Tag).

        If the table-metadata is tracked globally (Iceberg), Nessie returns a Content object, that contains the most up-to-date part for the globally tracked part (Iceberg: table-metadata) plus the per-Nessie-reference/hash specific part (Iceberg: snapshot-id, schema-id, partition-spec-id, default-sort-order-id).

        Parameters:
        ref - named-reference to retrieve the content for
        request - the ContentKeys to retrieve
        Returns:
        list of GetMultipleContentsResponse.ContentWithKeys
        Throws:
        NessieNotFoundException - if ref or hashOnRef does not exist