Package org.projectnessie.api.v2.http

Interface HttpTreeApi

  • All Superinterfaces:
    TreeApi
    @Consumes("application/json")
@Consumes("application/json")
@Path("v2/trees")
@Path("v2/trees")
public interface HttpTreeApi
extends TreeApi

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      SingleReferenceResponse assignReference​(java.lang.String type, java.lang.String ref, Reference assignTo)
      Update a reference's HEAD to point to a different commit.
      CommitResponse commitMultipleOperations​(java.lang.String branch, Operations operations)
      Commit multiple operations against the given branch expecting that branch to have the given hash as its latest commit.
      SingleReferenceResponse createReference​(java.lang.String name, java.lang.String type, Reference reference)
      Create a new reference.
      SingleReferenceResponse deleteReference​(java.lang.String type, java.lang.String ref)
      Delete a named reference.
      ReferencesResponse getAllReferences​(ReferencesParams params)
      Get all references.
      LogResponse getCommitLog​(java.lang.String ref, CommitLogParams params)
      Retrieve the commit log for a ref, potentially truncated by the backend.
      ContentResponse getContent​(ContentKey key, java.lang.String ref, boolean withDocumentation)
      This operation returns the Content for a ContentKey in a named-reference (a Branch or Tag).
      DiffResponse getDiff​(DiffParams params)
      Returns a set of content differences between two given references.
      EntriesResponse getEntries​(java.lang.String ref, EntriesParams params)
      Retrieve objects for a ref, potentially truncated by the backend.
      GetMultipleContentsResponse getMultipleContents​(java.lang.String ref, GetMultipleContentsRequest request, boolean withDocumentation)
      Similar to TreeApi.getContent(ContentKey, String, boolean), but takes multiple ContentKeys and returns the Content for the one or more ContentKeys in a named-reference (a Branch or Tag).
      SingleReferenceResponse getReferenceByName​(GetReferenceParams params)
      Get details of a particular ref, if it exists.
      GetMultipleContentsResponse getSeveralContents​(@Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") @Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") java.lang.String ref, java.util.List<java.lang.String> keys, boolean withDocumentation)  
      MergeResponse mergeRefIntoBranch​(java.lang.String branch, Merge merge)
      Merge commits from any reference onto a branch.
      MergeResponse transplantCommitsIntoBranch​(java.lang.String branch, Transplant transplant)
      Cherry-pick a set of commits into a branch.

    • Method Detail

      • getEntries

        @GET
@GET
@Produces("application/json")
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/entries")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/entries")
EntriesResponse getEntries​(@PathParam("ref") @PathParam("ref")
                           java.lang.String ref,
                           @BeanParam @BeanParam
                           EntriesParams params)
                    throws NessieNotFoundException
        Description copied from interface: TreeApi
        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.

        Specified by:
        getEntries in interface TreeApi
        Throws:
        NessieNotFoundException

      • getCommitLog

        @GET
@GET
@Produces("application/json")
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/history")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/history")
LogResponse getCommitLog​(@PathParam("ref") @PathParam("ref")
                         java.lang.String ref,
                         @BeanParam @BeanParam
                         CommitLogParams params)
                  throws NessieNotFoundException
        Description copied from interface: TreeApi
        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.

        Specified by:
        getCommitLog in interface TreeApi
        Throws:
        NessieNotFoundException

      • getDiff

        @GET
@GET
@Produces("application/json")
@Produces("application/json")
@Path("{from-ref:([^/]+|[^@]+(@|%40)[^@/]*)}/diff/{to-ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
@Path("{from-ref:([^/]+|[^@]+(@|%40)[^@/]*)}/diff/{to-ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
DiffResponse getDiff​(@BeanParam @BeanParam
                     DiffParams params)
              throws NessieNotFoundException
        Description copied from interface: TreeApi
        Returns a set of content differences between two given references.
        Specified by:
        getDiff in interface TreeApi
        Parameters:
        params - The DiffParams that includes the parameters for this API call.
        Returns:
        A set of diff values that show the difference between two given references.
        Throws:
        NessieNotFoundException

      • getContent

        @GET
@GET
@Produces("application/json")
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents/{key}")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents/{key}")
ContentResponse getContent​(@PathParam("key") @PathParam("key")
                           ContentKey key,
                           @PathParam("ref") @PathParam("ref")
                           java.lang.String ref,
                           @QueryParam("with-doc") @QueryParam("with-doc")
                           boolean withDocumentation)
                    throws NessieNotFoundException
        Description copied from interface: TreeApi
        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).

        Specified by:
        getContent in interface TreeApi
        Parameters:
        key - the ContentKeys to retrieve
        ref - named-reference to retrieve the content for
        withDocumentation - whether to return the documentation, if it exists.
        Returns:
        list of GetMultipleContentsResponse.ContentWithKeys
        Throws:
        NessieNotFoundException - if ref or hashOnRef does not exist

      • getSeveralContents

        @GET
@GET
@Produces("application/json")
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
GetMultipleContentsResponse getSeveralContents​(@Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") @Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") @PathParam("ref") @PathParam("ref")
                                               @Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") @Pattern(regexp="^((?:[A-Za-z](?:(?:(?![.][.])[A-Za-z0-9./_-])*[A-Za-z0-9_-])?)|-)?(?:@([0-9a-fA-F]{8,64})?)?(([~*^])([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{1,9}Z|([0-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 \'..\', optionally followed by @ and a hash with optional relative part. Hash with optional relative part must consist of either a valid commit hash (which in turn must consist of the hex representation of 4-32 bytes), or a valid relative part (which must be either \'~\' + a number representing the n-th predecessor of a commit, \'^\' + a number representing the n-th parent within a commit, or \'*\' + a number representing the created timestamp of a commit, in milliseconds since epoch or in ISO-8601 format), or both.") java.lang.String ref,
                                               @QueryParam("key") @QueryParam("key")
                                               java.util.List<java.lang.String> keys,
                                               @QueryParam("with-doc") @QueryParam("with-doc")
                                               boolean withDocumentation)
                                        throws NessieNotFoundException
        Throws:
        NessieNotFoundException

      • getMultipleContents

        @POST
@POST
@Produces("application/json")
@Produces("application/json")
@Consumes("application/json")
@Consumes("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
GetMultipleContentsResponse getMultipleContents​(@PathParam("ref") @PathParam("ref")
                                                java.lang.String ref,
                                                GetMultipleContentsRequest request,
                                                @QueryParam("with-doc") @QueryParam("with-doc")
                                                boolean withDocumentation)
                                         throws NessieNotFoundException
        Description copied from interface: TreeApi
        Similar to TreeApi.getContent(ContentKey, String, boolean), 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).

        Specified by:
        getMultipleContents in interface TreeApi
        Parameters:
        ref - named-reference to retrieve the content for
        request - the ContentKeys to retrieve
        withDocumentation - whether to return the documentation, if it exists.
        Returns:
        list of GetMultipleContentsResponse.ContentWithKeys
        Throws:
        NessieNotFoundException - if ref or hashOnRef does not exist

      • commitMultipleOperations

        @POST
@POST
@Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/commit")
@Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/commit")
@Produces("application/json")
@Produces("application/json")
@Consumes("application/json")
@Consumes("application/json")
CommitResponse commitMultipleOperations​(@PathParam("branch") @PathParam("branch")
                                        java.lang.String branch,
                                        Operations operations)
                                 throws NessieNotFoundException,
                                        NessieConflictException
        Description copied from interface: TreeApi
        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.
        Specified by:
        commitMultipleOperations in interface TreeApi
        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.