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 Details

    • getAllReferences

      @GET @GET @Produces("application/json") @Produces("application/json") ReferencesResponse getAllReferences(@BeanParam @BeanParam ReferencesParams params)
      Description copied from interface: TreeApi
      Get all references.
      Specified by:
      getAllReferences in interface TreeApi
      Returns:
      A ReferencesResponse instance containing all references.

    • createReference

      @POST @POST @Produces("application/json") @Produces("application/json") SingleReferenceResponse createReference(@QueryParam("name") @QueryParam("name") String name, @QueryParam("type") @QueryParam("type") String type, Reference reference) throws NessieNotFoundException, NessieConflictException
      Description copied from interface: TreeApi
      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".

      Specified by:
      createReference in interface TreeApi
      Throws:
      NessieNotFoundException
      NessieConflictException

    • getReferenceByName

      @GET @GET @Produces("application/json") @Produces("application/json") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") SingleReferenceResponse getReferenceByName(@BeanParam @BeanParam GetReferenceParams params) throws NessieNotFoundException
      Description copied from interface: TreeApi
      Get details of a particular ref, if it exists.
      Specified by:
      getReferenceByName in interface TreeApi
      Throws:
      NessieNotFoundException

    • getReferenceHistory

      @GET @GET @Produces("application/json") @Produces("application/json") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/recent-changes") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/recent-changes") ReferenceHistoryResponse getReferenceHistory(@BeanParam @BeanParam ReferenceHistoryParams params) throws NessieNotFoundException
      Description copied from interface: TreeApi
      Retrieve the recorded recent history of a reference.

      A reference's history is a size and time limited record of changes of the reference's current pointer, aka HEAD. The size and time limits are configured in the Nessie server configuration.

      Specified by:
      getReferenceHistory in interface TreeApi
      Throws:
      NessieNotFoundException

    • getEntries

      @GET @GET @Produces("application/json") @Produces("application/json") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/entries") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/entries") EntriesResponse getEntries(@PathParam("ref") @PathParam("ref") 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") 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

    • assignReference

      @PUT @PUT @Produces("application/json") @Produces("application/json") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") SingleReferenceResponse assignReference(@QueryParam("type") @QueryParam("type") String type, @PathParam("ref") @PathParam("ref") String ref, Reference assignTo) throws NessieNotFoundException, NessieConflictException
      Description copied from interface: TreeApi
      Update a reference's HEAD to point to a different commit.
      Specified by:
      assignReference in interface TreeApi
      Parameters:
      type - Optional expected type of reference being assigned. Will be validated if present.
      Throws:
      NessieNotFoundException
      NessieConflictException

    • deleteReference

      @DELETE @DELETE @Produces("application/json") @Produces("application/json") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") @Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}") SingleReferenceResponse deleteReference(@QueryParam("type") @QueryParam("type") String type, @PathParam("ref") @PathParam("ref") String ref) throws NessieConflictException, NessieNotFoundException
      Description copied from interface: TreeApi
      Delete a named reference.
      Specified by:
      deleteReference in interface TreeApi
      Parameters:
      type - Optional expected type of reference being deleted. Will be validated if present.
      Throws:
      NessieConflictException
      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") String ref, @QueryParam("with-doc") @QueryParam("with-doc") boolean withDocumentation, @QueryParam("for-write") @QueryParam("for-write") boolean forWrite) 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).

      Throws a AccessCheckException if access checks fail. Note that if the content object does not exist and the access checks fail, an AccessCheckException will be thrown, not a NessieContentNotFoundException.

      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.
      forWrite - If set to 'true', access control checks will check for write/create privilege in addition to read access checks.
      Returns:
      list of GetMultipleContentsResponse.ContentWithKeys
      Throws:
      NessieNotFoundException - If the content object or if ref does not exist a NessieContentNotFoundException or a NessieReferenceNotFoundException is being thrown.

    • 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.") String ref, @QueryParam("key") @QueryParam("key") List<String> keys, @QueryParam("with-doc") @QueryParam("with-doc") boolean withDocumentation, @QueryParam("for-write") @QueryParam("for-write") boolean forWrite) 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") String ref, GetMultipleContentsRequest request, @QueryParam("with-doc") @QueryParam("with-doc") boolean withDocumentation, @QueryParam("for-write") @QueryParam("for-write") boolean forWrite) throws NessieNotFoundException
      Description copied from interface: TreeApi
      Similar to TreeApi.getContent(ContentKey, String, boolean, 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).

      Throws an AccessCheckException if access checks fail.

      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.
      forWrite - If set to 'true', access control checks will check for write/create privilege in addition to read access checks.
      Returns:
      list of GetMultipleContentsResponse.ContentWithKeys
      Throws:
      NessieNotFoundException - Throws a NessieReferenceNotFoundException, if ref does not exist.

    • transplantCommitsIntoBranch

      @POST @POST @Produces("application/json") @Produces("application/json") @Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/transplant") @Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/transplant") MergeResponse transplantCommitsIntoBranch(@PathParam("branch") @PathParam("branch") String branch, Transplant transplant) throws NessieNotFoundException, NessieConflictException
      Description copied from interface: TreeApi
      Cherry-pick a set of commits into a branch.
      Specified by:
      transplantCommitsIntoBranch in interface TreeApi
      Throws:
      NessieNotFoundException
      NessieConflictException

    • mergeRefIntoBranch

      @POST @POST @Produces("application/json") @Produces("application/json") @Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/merge") @Path("{branch:([^/]+|[^@]+(@|%40)[^@/]*)}/history/merge") MergeResponse mergeRefIntoBranch(@PathParam("branch") @PathParam("branch") String branch, Merge merge) throws NessieNotFoundException, NessieConflictException
      Description copied from interface: TreeApi
      Merge commits from any reference onto a branch.
      Specified by:
      mergeRefIntoBranch in interface TreeApi
      Throws:
      NessieNotFoundException
      NessieConflictException

    • 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") 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.