Package com.linecorp.centraldogma.client

Interface CentralDogma

All Known Implementing Classes:

AbstractCentralDogma

public interface CentralDogma

Central Dogma client.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	createProject(String projectName)	Creates a project.
CompletableFuture<Void>	createRepository(String projectName, String repositoryName)	Creates a repository.
default <T> Watcher<T>	fileWatcher(String projectName, String repositoryName, Query<T> query)	Returns a Watcher which notifies its listeners when the result of the given Query becomes available or changes. e.g:
<T, U> Watcher<U>	fileWatcher(String projectName, String repositoryName, Query<T> query, Function<? super T,? extends U> function)	Returns a Watcher which notifies its listeners after applying the specified Function when the result of the given Query becomes available or changes. e.g:
<T, U> Watcher<U>	fileWatcher(String projectName, String repositoryName, Query<T> query, Function<? super T,? extends U> function, Executor executor)	Returns a Watcher which notifies its listeners after applying the specified Function when the result of the given Query becomes available or changes. e.g:
<T> CompletableFuture<Change<T>>	getDiff(String projectName, String repositoryName, Revision from, Revision to, Query<T> query)	Queries a file at two different revisions and returns the diff of the two Query results.
default CompletableFuture<Change<?>>	getDiff(String projectName, String repositoryName, Revision from, Revision to, String path)	Returns the diff of a file between two Revisions.
CompletableFuture<List<Change<?>>>	getDiffs(String projectName, String repositoryName, Revision from, Revision to, String pathPattern)	Retrieves the diffs of the files matched by the given path pattern between two Revisions.
<T> CompletableFuture<Entry<T>>	getFile(String projectName, String repositoryName, Revision revision, Query<T> query)	Queries a file at the specified revision and path with the specified Query.
default CompletableFuture<Entry<?>>	getFile(String projectName, String repositoryName, Revision revision, String path)	Retrieves the file at the specified revision and path.
CompletableFuture<Map<String,Entry<?>>>	getFiles(String projectName, String repositoryName, Revision revision, String pathPattern)	Retrieves the files matched by the path pattern.
default CompletableFuture<List<Commit>>	getHistory(String projectName, String repositoryName, Revision from, Revision to)	Retrieves the history of the repository between two Revisions.
CompletableFuture<List<Commit>>	getHistory(String projectName, String repositoryName, Revision from, Revision to, String pathPattern)	Retrieves the history of the files matched by the given path pattern between two Revisions.
default CompletableFuture<List<Change<?>>>	getPreviewDiffs(String projectName, String repositoryName, Revision baseRevision, Change<?>... changes)	Retrieves the preview diffs, which are hypothetical diffs generated if the specified Changes were successfully pushed to the specified repository.
CompletableFuture<List<Change<?>>>	getPreviewDiffs(String projectName, String repositoryName, Revision baseRevision, Iterable<? extends Change<?>> changes)	Retrieves the preview diffs, which are hypothetical diffs generated if the specified Changes were successfully pushed to the specified repository.
CompletableFuture<Map<String,EntryType>>	listFiles(String projectName, String repositoryName, Revision revision, String pathPattern)	Retrieves the list of the files matched by the given path pattern.
CompletableFuture<Set<String>>	listProjects()	Retrieves the list of the projects.
CompletableFuture<Set<String>>	listRemovedProjects()	Retrieves the list of the removed projects, which can be unremoved.
CompletableFuture<Set<String>>	listRemovedRepositories(String projectName)	Retrieves the list of the removed repositories, which can be unremoved.
CompletableFuture<Map<String,RepositoryInfo>>	listRepositories(String projectName)	Retrieves the list of the repositories.
<T> CompletableFuture<MergedEntry<T>>	mergeFiles(String projectName, String repositoryName, Revision revision, MergeQuery<T> mergeQuery)	Retrieves the merged entry of the specified MergeQuery at the specified revision.
default CompletableFuture<MergedEntry<?>>	mergeFiles(String projectName, String repositoryName, Revision revision, MergeSource... mergeSources)	Retrieves the merged entry of the specified MergeSources at the specified revision.
default CompletableFuture<MergedEntry<?>>	mergeFiles(String projectName, String repositoryName, Revision revision, Iterable<MergeSource> mergeSources)	Retrieves the merged entry of the specified MergeSources at the specified revision.
CompletableFuture<Revision>	normalizeRevision(String projectName, String repositoryName, Revision revision)	Converts the relative revision number to the absolute revision number. e.g.
CompletableFuture<Void>	purgeProject(String projectName)	Purges a project that was removed before.
CompletableFuture<Void>	purgeRepository(String projectName, String repositoryName)	Purges a repository that was removed before.
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, Change<?>... changes)	Deprecated. Use push(String, String, Revision, String, Change...).
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, Iterable<? extends Change<?>> changes)	Deprecated. Use push(String, String, Revision, String, Iterable).
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, String detail, Markup markup, Change<?>... changes)	Deprecated. Use push(String, String, Revision, String, String, Markup, Change...).
CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, String detail, Markup markup, Iterable<? extends Change<?>> changes)	Deprecated. Use push(String, String, Revision, String, String, Markup, Iterable).
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, String summary, Change<?>... changes)	Pushes the specified Changes to the repository.
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, String summary, Iterable<? extends Change<?>> changes)	Pushes the specified Changes to the repository.
default CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, String summary, String detail, Markup markup, Change<?>... changes)	Pushes the specified Changes to the repository.
CompletableFuture<PushResult>	push(String projectName, String repositoryName, Revision baseRevision, String summary, String detail, Markup markup, Iterable<? extends Change<?>> changes)	Pushes the specified Changes to the repository.
CompletableFuture<Void>	removeProject(String projectName)	Removes a project.
CompletableFuture<Void>	removeRepository(String projectName, String repositoryName)	Removes a repository.
default Watcher<Revision>	repositoryWatcher(String projectName, String repositoryName, String pathPattern)	Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:
<T> Watcher<T>	repositoryWatcher(String projectName, String repositoryName, String pathPattern, Function<Revision,? extends T> function)	Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:
<T> Watcher<T>	repositoryWatcher(String projectName, String repositoryName, String pathPattern, Function<Revision,? extends T> function, Executor executor)	Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:
CompletableFuture<Void>	unremoveProject(String projectName)	Unremoves a project.
CompletableFuture<Void>	unremoveRepository(String projectName, String repositoryName)	Unremoves a repository.
default <T> CompletableFuture<Entry<T>>	watchFile(String projectName, String repositoryName, Revision lastKnownRevision, Query<T> query)	Waits for the file matched by the specified Query to be changed since the specified lastKnownRevision.
<T> CompletableFuture<Entry<T>>	watchFile(String projectName, String repositoryName, Revision lastKnownRevision, Query<T> query, long timeoutMillis)	Waits for the file matched by the specified Query to be changed since the specified lastKnownRevision.
default CompletableFuture<Revision>	watchRepository(String projectName, String repositoryName, Revision lastKnownRevision, String pathPattern)	Waits for the files matched by the specified pathPattern to be changed since the specified lastKnownRevision.
CompletableFuture<Revision>	watchRepository(String projectName, String repositoryName, Revision lastKnownRevision, String pathPattern, long timeoutMillis)	Waits for the files matched by the specified pathPattern to be changed since the specified lastKnownRevision.

Method Details

createProject

CompletableFuture<Void> createProject(String projectName)

Creates a project.

removeProject

CompletableFuture<Void> removeProject(String projectName)

Removes a project. A removed project can be unremoved using unremoveProject(String).

purgeProject

CompletableFuture<Void> purgeProject(String projectName)

Purges a project that was removed before.

unremoveProject

CompletableFuture<Void> unremoveProject(String projectName)

Unremoves a project.

listProjects

CompletableFuture<Set<String>> listProjects()

Retrieves the list of the projects.

Returns:

a Set that contains the names of the projects

listRemovedProjects

CompletableFuture<Set<String>> listRemovedProjects()

Retrieves the list of the removed projects, which can be unremoved.

Returns:

a Set that contains the names of the removed projects

createRepository

CompletableFuture<Void> createRepository(String projectName, String repositoryName)

Creates a repository.

removeRepository

CompletableFuture<Void> removeRepository(String projectName, String repositoryName)

Removes a repository. A removed repository can be unremoved using unremoveRepository(String, String).

purgeRepository

CompletableFuture<Void> purgeRepository(String projectName, String repositoryName)

Purges a repository that was removed before.

unremoveRepository

CompletableFuture<Void> unremoveRepository(String projectName, String repositoryName)

Unremoves a repository.

listRepositories

CompletableFuture<Map<String,RepositoryInfo>> listRepositories(String projectName)

Retrieves the list of the repositories.

Returns:

a Map of repository name and RepositoryInfo pairs

listRemovedRepositories

CompletableFuture<Set<String>> listRemovedRepositories(String projectName)

Retrieves the list of the removed repositories, which can be unremoved.

Returns:

a Set that contains the names of the removed repositories

normalizeRevision

CompletableFuture<Revision> normalizeRevision(String projectName, String repositoryName, Revision revision)

Converts the relative revision number to the absolute revision number. e.g. -1 -> 3

Returns:

the absolute Revision

listFiles

CompletableFuture<Map<String,EntryType>> listFiles(String projectName, String repositoryName, Revision revision, String pathPattern)

Retrieves the list of the files matched by the given path pattern. A path pattern is a variant of glob:

• "/**" - find all files recursively
• "*.json" - find all JSON files recursively
• "/foo/*.json" - find all JSON files under the directory /foo
• "/*/foo.txt" - find all files named foo.txt at the second depth level
• "*.json,/bar/*.txt" - use comma to specify more than one pattern. A file will be matched if any pattern matches.

Returns:

a Map of file path and type pairs

getFile

default CompletableFuture<Entry<?>> getFile(String projectName, String repositoryName, Revision revision, String path)

Retrieves the file at the specified revision and path. This method is a shortcut of getFile(projectName, repositoryName, revision, Query.identity(path). Consider using getFile(String, String, Revision, Query) with Query.ofText(String) or Query.ofJson(String) if you already know the file type.

Returns:

the Entry at the given path

getFile

<T> CompletableFuture<Entry<T>> getFile(String projectName, String repositoryName, Revision revision, Query<T> query)

Queries a file at the specified revision and path with the specified Query.

Returns:

the Entry that is matched by the given Query

getFiles

CompletableFuture<Map<String,Entry<?>>> getFiles(String projectName, String repositoryName, Revision revision, String pathPattern)

Retrieves the files matched by the path pattern. A path pattern is a variant of glob:

• "/**" - find all files recursively
• "*.json" - find all JSON files recursively
• "/foo/*.json" - find all JSON files under the directory /foo
• "/*/foo.txt" - find all files named foo.txt at the second depth level
• "*.json,/bar/*.txt" - use comma to specify more than one pattern. A file will be matched if any pattern matches.

Returns:

a Map of file path and Entry pairs

mergeFiles

default CompletableFuture<MergedEntry<?>> mergeFiles(String projectName, String repositoryName, Revision revision, MergeSource... mergeSources)

Retrieves the merged entry of the specified MergeSources at the specified revision. Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in the mergeSources.

Note that only ObjectNode is recursively merged traversing the children. Other node types are simply replaced.

Returns:

the MergedEntry which contains the result of the merge

mergeFiles

default CompletableFuture<MergedEntry<?>> mergeFiles(String projectName, String repositoryName, Revision revision, Iterable<MergeSource> mergeSources)

Retrieves the merged entry of the specified MergeSources at the specified revision. Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in the mergeSources.

Note that only ObjectNode is recursively merged traversing the children. Other node types are simply replaced.

Returns:

the MergedEntry which contains the result of the merge

mergeFiles

<T> CompletableFuture<MergedEntry<T>> mergeFiles(String projectName, String repositoryName, Revision revision, MergeQuery<T> mergeQuery)

Retrieves the merged entry of the specified MergeQuery at the specified revision. Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in the MergeQuery.

Note that only ObjectNode is recursively merged traversing the children. Other node types are simply replaced.

Returns:

the MergedEntry which contains the result of the merge

getHistory

default CompletableFuture<List<Commit>> getHistory(String projectName, String repositoryName, Revision from, Revision to)

Retrieves the history of the repository between two Revisions. This method is a shortcut of getHistory(projectName, repositoryName, from, to, "/**"). Note that this method does not retrieve the diffs but only metadata about the changes. Use getDiff(String, String, Revision, Revision, Query) or getDiffs(String, String, Revision, Revision, String) to retrieve the diffs.

Returns:

a List that contains the Commits of the specified repository

getHistory

CompletableFuture<List<Commit>> getHistory(String projectName, String repositoryName, Revision from, Revision to, String pathPattern)

Retrieves the history of the files matched by the given path pattern between two Revisions. A path pattern is a variant of glob:

• "/**" - find all files recursively
• "*.json" - find all JSON files recursively
• "/foo/*.json" - find all JSON files under the directory /foo
• "/*/foo.txt" - find all files named foo.txt at the second depth level
• "*.json,/bar/*.txt" - use comma to specify more than one pattern. A file will be matched if any pattern matches.

Note that this method does not retrieve the diffs but only metadata about the changes. Use getDiff(String, String, Revision, Revision, Query) or getDiffs(String, String, Revision, Revision, String) to retrieve the diffs.

Returns:

a List that contains the Commits of the files matched by the given pathPattern in the specified repository

getDiff

default CompletableFuture<Change<?>> getDiff(String projectName, String repositoryName, Revision from, Revision to, String path)

Returns the diff of a file between two Revisions. This method is a shortcut of getDiff(projectName, repositoryName, from, to, Query.identity(path)). Consider using getDiff(String, String, Revision, Revision, Query) with Query.ofText(String) or Query.ofJson(String) if you already know the file type.

Returns:

the Change that contains the diff of the given path between the specified two revisions

getDiff

<T> CompletableFuture<Change<T>> getDiff(String projectName, String repositoryName, Revision from, Revision to, Query<T> query)

Queries a file at two different revisions and returns the diff of the two Query results.

Returns:

the Change that contains the diff of the file matched by the given query between the specified two revisions

getDiffs

CompletableFuture<List<Change<?>>> getDiffs(String projectName, String repositoryName, Revision from, Revision to, String pathPattern)

Retrieves the diffs of the files matched by the given path pattern between two Revisions. A path pattern is a variant of glob:

• "/**" - find all files recursively
• "*.json" - find all JSON files recursively
• "/foo/*.json" - find all JSON files under the directory /foo
• "/*/foo.txt" - find all files named foo.txt at the second depth level
• "*.json,/bar/*.txt" - use comma to specify more than one pattern. A file will be matched if any pattern matches.

Returns:

a List of the Changes that contain the diffs between the files matched by the given pathPattern between two revisions.

getPreviewDiffs

default CompletableFuture<List<Change<?>>> getPreviewDiffs(String projectName, String repositoryName, Revision baseRevision, Change<?>... changes)

Retrieves the preview diffs, which are hypothetical diffs generated if the specified Changes were successfully pushed to the specified repository. This operation is useful for pre-checking if the specified Changes will be applied as expected without any conflicts.

Returns:

the diffs which would be committed if the specified Changes were pushed successfully

getPreviewDiffs

CompletableFuture<List<Change<?>>> getPreviewDiffs(String projectName, String repositoryName, Revision baseRevision, Iterable<? extends Change<?>> changes)

Retrieves the preview diffs, which are hypothetical diffs generated if the specified Changes were successfully pushed to the specified repository. This operation is useful for pre-checking if the specified Changes will be applied as expected without any conflicts.

Returns:

the diffs which would be committed if the specified Changes were pushed successfully

push

default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, String summary, Change<?>... changes)

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, String summary, Iterable<? extends Change<?>> changes)

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, String summary, String detail, Markup markup, Change<?>... changes)

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, String summary, String detail, Markup markup, Iterable<? extends Change<?>> changes)

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

@Deprecated default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, Change<?>... changes)

Deprecated.

Use push(String, String, Revision, String, Change...).

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

@Deprecated default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, Iterable<? extends Change<?>> changes)

Deprecated.

Use push(String, String, Revision, String, Iterable).

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

@Deprecated default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, String detail, Markup markup, Change<?>... changes)

Deprecated.

Use push(String, String, Revision, String, String, Markup, Change...).

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

push

@Deprecated CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, Author author, String summary, String detail, Markup markup, Iterable<? extends Change<?>> changes)

Deprecated.

Use push(String, String, Revision, String, String, Markup, Iterable).

Pushes the specified Changes to the repository.

Returns:

the PushResult which tells the Revision and timestamp of the new Commit

watchRepository

default CompletableFuture<Revision> watchRepository(String projectName, String repositoryName, Revision lastKnownRevision, String pathPattern)

Waits for the files matched by the specified pathPattern to be changed since the specified lastKnownRevision. If no changes were made within 1 minute, the returned CompletableFuture will be completed with null.

Returns:

the latest known Revision which contains the changes for the matched files. null if the files were not changed for 1 minute since the invocation of this method.

watchRepository

CompletableFuture<Revision> watchRepository(String projectName, String repositoryName, Revision lastKnownRevision, String pathPattern, long timeoutMillis)

Waits for the files matched by the specified pathPattern to be changed since the specified lastKnownRevision. If no changes were made within the specified timeoutMillis, the returned CompletableFuture will be completed with null. It is recommended to specify the largest timeoutMillis allowed by the server. If unsure, use watchRepository(String, String, Revision, String).

Returns:

the latest known Revision which contains the changes for the matched files. null if the files were not changed for timeoutMillis milliseconds since the invocation of this method.

watchFile

default <T> CompletableFuture<Entry<T>> watchFile(String projectName, String repositoryName, Revision lastKnownRevision, Query<T> query)

Waits for the file matched by the specified Query to be changed since the specified lastKnownRevision. If no changes were made within 1 minute, the returned CompletableFuture will be completed with null.

Returns:

the Entry which contains the latest known Query result. null if the file was not changed for 1 minute since the invocation of this method.

watchFile

<T> CompletableFuture<Entry<T>> watchFile(String projectName, String repositoryName, Revision lastKnownRevision, Query<T> query, long timeoutMillis)

Waits for the file matched by the specified Query to be changed since the specified lastKnownRevision. If no changes were made within the specified timeoutMillis, the returned CompletableFuture will be completed with null. It is recommended to specify the largest timeoutMillis allowed by the server. If unsure, use watchFile(String, String, Revision, Query).

Returns:

the Entry which contains the latest known Query result. null if the file was not changed for timeoutMillis milliseconds since the invocation of this method.

fileWatcher

default <T> Watcher<T> fileWatcher(String projectName, String repositoryName, Query<T> query)

Returns a Watcher which notifies its listeners when the result of the given Query becomes available or changes. e.g:

 Watcher<JsonNode> watcher = client.fileWatcher("foo", "bar", Query.ofJson("/baz.json"));

 watcher.watch((revision, content) -> {
     assert content instanceof JsonNode;
     ...
 });

fileWatcher

<T, U> Watcher<U> fileWatcher(String projectName, String repositoryName, Query<T> query, Function<? super T,? extends U> function)

Returns a Watcher which notifies its listeners after applying the specified Function when the result of the given Query becomes available or changes. e.g:

 Watcher<MyType> watcher = client.fileWatcher(
         "foo", "bar", Query.ofJson("/baz.json"),
         content -> new ObjectMapper().treeToValue(content, MyType.class));

 watcher.watch((revision, myValue) -> {
     assert myValue instanceof MyType;
     ...
 });

Note that Function by default is executed by a blocking task executor so that you can safely call a blocking operation.

fileWatcher

<T, U> Watcher<U> fileWatcher(String projectName, String repositoryName, Query<T> query, Function<? super T,? extends U> function, Executor executor)

Returns a Watcher which notifies its listeners after applying the specified Function when the result of the given Query becomes available or changes. e.g:

 Watcher<MyType> watcher = client.fileWatcher(
         "foo", "bar", Query.ofJson("/baz.json"),
         content -> new ObjectMapper().treeToValue(content, MyType.class), executor);

 watcher.watch((revision, myValue) -> {
     assert myValue instanceof MyType;
     ...
 });

Parameters:

executor - the Executor that executes the Function

repositoryWatcher

default Watcher<Revision> repositoryWatcher(String projectName, String repositoryName, String pathPattern)

Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:

 Watcher<Revision> watcher = client.repositoryWatcher("foo", "bar", "/*.json");

 watcher.watch(revision -> {
     ...
 });

repositoryWatcher

<T> Watcher<T> repositoryWatcher(String projectName, String repositoryName, String pathPattern, Function<Revision,? extends T> function)

Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:

 Watcher<Map<String, Entry<?>> watcher = client.repositoryWatcher(
         "foo", "bar", "/*.json", revision -> client.getFiles("foo", "bar", revision, "/*.json").join());

 watcher.watch((revision, contents) -> {
     ...
 });

Function by default is executed by a blocking task executor so that you can safely call a blocking operation.

Note that you may get RevisionNotFoundException during the getFiles() call and may have to retry in the above example due to a known issue.

repositoryWatcher

<T> Watcher<T> repositoryWatcher(String projectName, String repositoryName, String pathPattern, Function<Revision,? extends T> function, Executor executor)

Returns a Watcher which notifies its listeners when the specified repository has a new commit that contains the changes for the files matched by the given pathPattern. e.g:

 Watcher<Map<String, Entry<?>> watcher = client.repositoryWatcher(
         "foo", "bar", "/*.json",
         revision -> client.getFiles("foo", "bar", revision, "/*.json").join(), executor);

 watcher.watch((revision, contents) -> {
     ...
 });

Note that you may get RevisionNotFoundException during the getFiles() call and may have to retry in the above example due to a known issue.

Parameters:

executor - the Executor that executes the Function