Package org.projectnessie.api.v2.http

Interface HttpTreeApi

All Superinterfaces:

TreeApi

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

Method Summary

Modifier and Type	Method	Description
SingleReferenceResponse	assignReference(Reference.ReferenceType 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, Reference.ReferenceType type, Reference reference)	Create a new reference.
SingleReferenceResponse	deleteReference(Reference.ReferenceType 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)	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)	Similar to TreeApi.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(GetReferenceParams params)	Get details of a particular ref, if it exists.
GetMultipleContentsResponse	getSeveralContents(java.lang.String ref, java.util.List<java.lang.String> keys)
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

getAllReferences

@GET
@Produces("application/json")
ReferencesResponse getAllReferences(@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
@Produces("application/json")
SingleReferenceResponse createReference(@QueryParam("name")
                                        java.lang.String name,
                                        @QueryParam("type")
                                        Reference.ReferenceType 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
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
SingleReferenceResponse getReferenceByName(@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

getEntries

@GET
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/entries")
EntriesResponse getEntries(@PathParam("ref")
                           java.lang.String ref,
                           @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
@Produces("application/json")
@Path("{ref}/history")
LogResponse getCommitLog(@PathParam("ref")
                         java.lang.String ref,
                         @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
@Produces("application/json")
@Path("{from-ref:([^/]+|[^@]+(@|%40)[^@/]*)}/diff/{to-ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
DiffResponse getDiff(@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
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
SingleReferenceResponse assignReference(@QueryParam("type")
                                        Reference.ReferenceType type,
                                        @PathParam("ref")
                                        java.lang.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
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}")
SingleReferenceResponse deleteReference(@QueryParam("type")
                                        Reference.ReferenceType type,
                                        @PathParam("ref")
                                        java.lang.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
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents/{key}")
ContentResponse getContent(@PathParam("key")
                           ContentKey key,
                           @PathParam("ref")
                           java.lang.String ref)
                    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

Returns:

list of GetMultipleContentsResponse.ContentWithKeys

Throws:

NessieNotFoundException - if ref or hashOnRef does not exist

getSeveralContents

@GET
@Produces("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
GetMultipleContentsResponse getSeveralContents(@PathParam("ref")
                                               java.lang.String ref,
                                               @QueryParam("key")
                                               java.util.List<java.lang.String> keys)
                                        throws NessieNotFoundException

Throws:

NessieNotFoundException

getMultipleContents

@POST
@Produces("application/json")
@Consumes("application/json")
@Path("{ref:([^/]+|[^@]+(@|%40)[^@/]*)}/contents")
GetMultipleContentsResponse getMultipleContents(@PathParam("ref")
                                                java.lang.String ref,
                                                GetMultipleContentsRequest request)
                                         throws NessieNotFoundException

Description copied from interface: TreeApi

Similar to TreeApi.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).

Specified by:

getMultipleContents in interface TreeApi

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

transplantCommitsIntoBranch

@POST
@Produces("application/json")
@Path("{branch}/history/transplant")
MergeResponse transplantCommitsIntoBranch(@PathParam("branch")
                                          java.lang.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
@Produces("application/json")
@Path("{branch}/history/merge")
MergeResponse mergeRefIntoBranch(@PathParam("branch")
                                 java.lang.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
@Path("{branch}/history/commit")
@Produces("application/json")
@Consumes("application/json")
CommitResponse commitMultipleOperations(@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.