1 /* 2 * Copyright 2017 LINE Corporation 3 * 4 * LINE Corporation licenses this file to you under the Apache License, 5 * version 2.0 (the "License"); you may not use this file except in compliance 6 * with the License. You may obtain a copy of the License at: 7 * 8 * https://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations 14 * under the License. 15 */ 16 package com.linecorp.centraldogma.client; 17 18 import static com.linecorp.centraldogma.internal.PathPatternUtil.toPathPattern; 19 import static java.util.Objects.requireNonNull; 20 21 import java.util.List; 22 import java.util.Map; 23 import java.util.Set; 24 import java.util.concurrent.CompletableFuture; 25 import java.util.concurrent.Executor; 26 import java.util.function.Function; 27 28 import com.fasterxml.jackson.databind.node.ObjectNode; 29 import com.google.common.collect.ImmutableList; 30 31 import com.linecorp.centraldogma.common.Author; 32 import com.linecorp.centraldogma.common.Change; 33 import com.linecorp.centraldogma.common.Commit; 34 import com.linecorp.centraldogma.common.Entry; 35 import com.linecorp.centraldogma.common.EntryNotFoundException; 36 import com.linecorp.centraldogma.common.EntryType; 37 import com.linecorp.centraldogma.common.Markup; 38 import com.linecorp.centraldogma.common.MergeQuery; 39 import com.linecorp.centraldogma.common.MergeSource; 40 import com.linecorp.centraldogma.common.MergedEntry; 41 import com.linecorp.centraldogma.common.PathPattern; 42 import com.linecorp.centraldogma.common.PushResult; 43 import com.linecorp.centraldogma.common.Query; 44 import com.linecorp.centraldogma.common.QueryType; 45 import com.linecorp.centraldogma.common.Revision; 46 import com.linecorp.centraldogma.common.RevisionNotFoundException; 47 48 /** 49 * Central Dogma client. 50 */ 51 public interface CentralDogma { 52 53 /** 54 * Returns a new {@link CentralDogmaRepository} that is used to send a request to the specified 55 * {@code projectName} and {@code repositoryName}. 56 */ 57 CentralDogmaRepository forRepo(String projectName, String repositoryName); 58 59 /** 60 * Creates a project. 61 */ 62 CompletableFuture<Void> createProject(String projectName); 63 64 /** 65 * Removes a project. A removed project can be unremoved using {@link #unremoveProject(String)}. 66 */ 67 CompletableFuture<Void> removeProject(String projectName); 68 69 /** 70 * Purges a project that was removed before. 71 */ 72 CompletableFuture<Void> purgeProject(String projectName); 73 74 /** 75 * Unremoves a project. 76 */ 77 CompletableFuture<Void> unremoveProject(String projectName); 78 79 /** 80 * Retrieves the list of the projects. 81 * 82 * @return a {@link Set} that contains the names of the projects 83 */ 84 CompletableFuture<Set<String>> listProjects(); 85 86 /** 87 * Retrieves the list of the removed projects, which can be {@linkplain #unremoveProject(String) unremoved}. 88 * 89 * @return a {@link Set} that contains the names of the removed projects 90 */ 91 CompletableFuture<Set<String>> listRemovedProjects(); 92 93 /** 94 * Creates a repository. 95 */ 96 CompletableFuture<CentralDogmaRepository> createRepository(String projectName, String repositoryName); 97 98 /** 99 * Removes a repository. A removed repository can be unremoved using 100 * {@link #unremoveRepository(String, String)}. 101 */ 102 CompletableFuture<Void> removeRepository(String projectName, String repositoryName); 103 104 /** 105 * Purges a repository that was removed before. 106 */ 107 CompletableFuture<Void> purgeRepository(String projectName, String repositoryName); 108 109 /** 110 * Unremoves a repository. 111 */ 112 CompletableFuture<CentralDogmaRepository> unremoveRepository(String projectName, String repositoryName); 113 114 /** 115 * Retrieves the list of the repositories. 116 * 117 * @return a {@link Map} of repository name and {@link RepositoryInfo} pairs 118 */ 119 CompletableFuture<Map<String, RepositoryInfo>> listRepositories(String projectName); 120 121 /** 122 * Retrieves the list of the removed repositories, which can be 123 * {@linkplain #unremoveRepository(String, String) unremoved}. 124 * 125 * @return a {@link Set} that contains the names of the removed repositories 126 */ 127 CompletableFuture<Set<String>> listRemovedRepositories(String projectName); 128 129 /** 130 * Converts the relative revision number to the absolute revision number. e.g. {@code -1 -> 3} 131 * 132 * @return the absolute {@link Revision} 133 */ 134 CompletableFuture<Revision> normalizeRevision(String projectName, String repositoryName, Revision revision); 135 136 /** 137 * Retrieves the list of the files matched by the given path pattern. 138 * 139 * @return a {@link Map} of file path and type pairs 140 * 141 * @deprecated Use {@link FilesRequest#list(Revision)} via {@link CentralDogmaRepository#file(PathPattern)}. 142 */ 143 @Deprecated 144 default CompletableFuture<Map<String, EntryType>> listFiles(String projectName, String repositoryName, 145 Revision revision, String pathPattern) { 146 return listFiles(projectName, repositoryName, revision, toPathPattern(pathPattern)); 147 } 148 149 /** 150 * Retrieves the list of the files matched by the given {@link PathPattern}. 151 * This method is equivalent to calling: 152 * <pre>{@code 153 * CentralDogma dogma = ... 154 * dogma.forRepo(projectName, repositoryName) 155 * .files(pathPattern) 156 * .list(revision); 157 * }</pre> 158 * 159 * @return a {@link Map} of file path and type pairs 160 */ 161 CompletableFuture<Map<String, EntryType>> listFiles(String projectName, String repositoryName, 162 Revision revision, PathPattern pathPattern); 163 164 /** 165 * Retrieves the file at the specified revision and path. This method is a shortcut of 166 * {@code getFile(projectName, repositoryName, revision, Query.identity(path)}. 167 * Consider using {@link #getFile(String, String, Revision, Query)} with {@link Query#ofText(String)} or 168 * {@link Query#ofJson(String)} if you already know the file type. 169 * 170 * @return the {@link Entry} at the given {@code path} 171 * 172 * @deprecated Use {@link FileRequest#get(Revision)} via {@link CentralDogmaRepository#file(String)}. 173 */ 174 @Deprecated 175 default CompletableFuture<Entry<?>> getFile(String projectName, String repositoryName, 176 Revision revision, String path) { 177 @SuppressWarnings("unchecked") 178 final CompletableFuture<Entry<?>> f = (CompletableFuture<Entry<?>>) (CompletableFuture<?>) 179 getFile(projectName, repositoryName, revision, Query.of(QueryType.IDENTITY, path)); 180 return f; 181 } 182 183 /** 184 * Queries a file at the specified revision and path with the specified {@link Query}. 185 * This method is equivalent to calling: 186 * <pre>{@code 187 * CentralDogma dogma = ... 188 * dogma.forRepo(projectName, repositoryName) 189 * .file(query) 190 * .get(revision); 191 * }</pre> 192 * 193 * @return the {@link Entry} that is matched by the given {@link Query} 194 */ 195 <T> CompletableFuture<Entry<T>> getFile(String projectName, String repositoryName, 196 Revision revision, Query<T> query); 197 198 /** 199 * Retrieves the files matched by the path pattern. 200 * 201 * @return a {@link Map} of file path and {@link Entry} pairs 202 * 203 * @deprecated Use {@link FilesRequest#get(Revision)} via {@link CentralDogmaRepository#file(PathPattern)}. 204 */ 205 @Deprecated 206 default CompletableFuture<Map<String, Entry<?>>> getFiles(String projectName, String repositoryName, 207 Revision revision, String pathPattern) { 208 return getFiles(projectName, repositoryName, revision, toPathPattern(pathPattern)); 209 } 210 211 /** 212 * Retrieves the files matched by the {@link PathPattern}. 213 * This method is equivalent to calling: 214 * <pre>{@code 215 * CentralDogma dogma = ... 216 * dogma.forRepo(projectName, repositoryName) 217 * .file(pathPattern) 218 * .get(revision); 219 * }</pre> 220 * 221 * @return a {@link Map} of file path and {@link Entry} pairs 222 */ 223 CompletableFuture<Map<String, Entry<?>>> getFiles(String projectName, String repositoryName, 224 Revision revision, PathPattern pathPattern); 225 226 /** 227 * Retrieves the merged entry of the specified {@link MergeSource}s at the specified revision. 228 * Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in 229 * the {@code mergeSources}. 230 * 231 * <p>Note that only {@link ObjectNode} is recursively merged traversing the children. Other node types are 232 * simply replaced. 233 * 234 * @return the {@link MergedEntry} which contains the result of the merge 235 * 236 * @deprecated Use {@link MergeRequest#get(Revision)} via 237 * {@link CentralDogmaRepository#merge(MergeSource...)}. 238 */ 239 @Deprecated 240 default CompletableFuture<MergedEntry<?>> mergeFiles( 241 String projectName, String repositoryName, 242 Revision revision, MergeSource... mergeSources) { 243 return mergeFiles(projectName, repositoryName, revision, 244 ImmutableList.copyOf(requireNonNull(mergeSources, "mergeSources"))); 245 } 246 247 /** 248 * Retrieves the merged entry of the specified {@link MergeSource}s at the specified revision. 249 * Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in 250 * the {@code mergeSources}. 251 * 252 * <p>Note that only {@link ObjectNode} is recursively merged traversing the children. Other node types are 253 * simply replaced. 254 * 255 * @return the {@link MergedEntry} which contains the result of the merge 256 * 257 * @deprecated Use {@link MergeRequest#get(Revision)} via 258 * {@link CentralDogmaRepository#merge(Iterable)}. 259 */ 260 @Deprecated 261 default CompletableFuture<MergedEntry<?>> mergeFiles( 262 String projectName, String repositoryName, 263 Revision revision, Iterable<MergeSource> mergeSources) { 264 @SuppressWarnings("unchecked") 265 final CompletableFuture<MergedEntry<?>> future = 266 (CompletableFuture<MergedEntry<?>>) (CompletableFuture<?>) mergeFiles( 267 projectName, repositoryName, revision, MergeQuery.ofJson(mergeSources)); 268 return future; 269 } 270 271 /** 272 * Retrieves the merged entry of the specified {@link MergeQuery} at the specified revision. 273 * Only JSON entry merge is currently supported. The JSON files are merged sequentially as specified in 274 * the {@link MergeQuery}. 275 * This method is equivalent to calling: 276 * <pre>{@code 277 * CentralDogma dogma = ... 278 * dogma.forRepo(projectName, repositoryName) 279 * .merge(mergeQuery) 280 * .get(revision); 281 * }</pre> 282 * 283 * <p>Note that only {@link ObjectNode} is recursively merged traversing the children. Other node types are 284 * simply replaced. 285 * 286 * @return the {@link MergedEntry} which contains the result of the merge 287 */ 288 <T> CompletableFuture<MergedEntry<T>> mergeFiles(String projectName, String repositoryName, 289 Revision revision, MergeQuery<T> mergeQuery); 290 291 /** 292 * Retrieves the history of the repository between two {@link Revision}s. This method is a shortcut of 293 * {@code getHistory(projectName, repositoryName, from, to, "/**")}. Note that this method does not 294 * retrieve the diffs but only metadata about the changes. 295 * Use {@link #getDiff(String, String, Revision, Revision, Query)} or 296 * {@link #getDiff(String, String, Revision, Revision, PathPattern)} to retrieve the diffs. 297 * 298 * @return a {@link List} that contains the {@link Commit}s of the specified repository 299 * 300 * @deprecated Use {@link HistoryRequest#get(Revision, Revision)} via 301 * {@link CentralDogmaRepository#history()}. 302 */ 303 @Deprecated 304 default CompletableFuture<List<Commit>> getHistory( 305 String projectName, String repositoryName, Revision from, Revision to) { 306 return getHistory(projectName, repositoryName, from, to, "/**"); 307 } 308 309 /** 310 * Retrieves the history of the files matched by the given path pattern between two {@link Revision}s. 311 * 312 * <p>Note that this method does not retrieve the diffs but only metadata about the changes. 313 * Use {@link #getDiff(String, String, Revision, Revision, Query)} or 314 * {@link #getDiff(String, String, Revision, Revision, PathPattern)} to retrieve the diffs. 315 * 316 * @return a {@link List} that contains the {@link Commit}s of the files matched by the given 317 * {@link PathPattern} in the specified repository 318 * 319 * @deprecated Use {@link HistoryRequest#get(Revision, Revision)} via 320 * {@link CentralDogmaRepository#history(PathPattern)}. 321 */ 322 @Deprecated 323 default CompletableFuture<List<Commit>> getHistory( 324 String projectName, String repositoryName, Revision from, Revision to, String pathPattern) { 325 return getHistory(projectName, repositoryName, from, to, toPathPattern(pathPattern), 0); 326 } 327 328 /** 329 * Retrieves the history of the files matched by the given {@link PathPattern} between 330 * two {@link Revision}s. 331 * 332 * <p>Note that this method does not retrieve the diffs but only metadata about the changes. 333 * Use {@link DiffRequest} to retrieve the diffs. 334 * 335 * @return a {@link List} that contains the {@link Commit}s of the files matched by the given 336 * {@link PathPattern} in the specified repository 337 * 338 * @deprecated Use {@link HistoryRequest#get(Revision, Revision)} via 339 * {@link CentralDogmaRepository#history(PathPattern)}. 340 */ 341 @Deprecated 342 default CompletableFuture<List<Commit>> getHistory( 343 String projectName, String repositoryName, Revision from, Revision to, 344 PathPattern pathPattern) { 345 return getHistory(projectName, repositoryName, from, to, pathPattern, 0); 346 } 347 348 /** 349 * Retrieves the history of the files matched by the given {@link PathPattern} between 350 * two {@link Revision}s. 351 * This method is equivalent to calling: 352 * <pre>{@code 353 * CentralDogma dogma = ... 354 * dogma.forRepo(projectName, repositoryName) 355 * .history(pathPattern) 356 * .maxCommits(maxCommits) 357 * .get(from, to); 358 * }</pre> 359 * 360 * <p>Note that this method does not retrieve the diffs but only metadata about the changes. 361 * Use {@link DiffRequest} to retrieve the diffs. 362 * 363 * @return a {@link List} that contains the {@link Commit}s of the files matched by the given 364 * {@link PathPattern} in the specified repository 365 */ 366 CompletableFuture<List<Commit>> getHistory( 367 String projectName, String repositoryName, Revision from, Revision to, 368 PathPattern pathPattern, int maxCommits); 369 370 /** 371 * Returns the diff of a file between two {@link Revision}s. This method is a shortcut of 372 * {@code getDiff(projectName, repositoryName, from, to, Query.identity(path))}. 373 * Consider using {@link #getDiff(String, String, Revision, Revision, Query)} with 374 * {@link Query#ofText(String)} or {@link Query#ofJson(String)} if you already know the file type. 375 * 376 * @return the {@link Change} that contains the diff of the given {@code path} between the specified 377 * two revisions 378 * 379 * @deprecated Use {@link DiffRequest#get(Revision, Revision)} via 380 * {@link CentralDogmaRepository#diff(String)}. 381 */ 382 @Deprecated 383 default CompletableFuture<Change<?>> getDiff(String projectName, String repositoryName, 384 Revision from, Revision to, String path) { 385 @SuppressWarnings({ "unchecked", "rawtypes" }) 386 final CompletableFuture<Change<?>> diff = (CompletableFuture<Change<?>>) (CompletableFuture) 387 getDiff(projectName, repositoryName, from, to, Query.of(QueryType.IDENTITY, path)); 388 return diff; 389 } 390 391 /** 392 * Queries a file at two different revisions and returns the diff of the two {@link Query} results. 393 * This method is equivalent to calling: 394 * <pre>{@code 395 * CentralDogma dogma = ... 396 * dogma.forRepo(projectName, repositoryName) 397 * .diff(query) 398 * .get(from, to); 399 * }</pre> 400 * 401 * @return the {@link Change} that contains the diff of the file matched by the given {@code query} 402 * between the specified two revisions 403 */ 404 <T> CompletableFuture<Change<T>> getDiff(String projectName, String repositoryName, 405 Revision from, Revision to, Query<T> query); 406 407 /** 408 * Retrieves the diffs of the files matched by the given {@link PathPattern} between two {@link Revision}s. 409 * <pre>{@code 410 * CentralDogma dogma = ... 411 * dogma.forRepo(projectName, repositoryName) 412 * .diff(pathPattern) 413 * .get(from, to); 414 * }</pre> 415 * 416 * @return a {@link List} of the {@link Change}s that contain the diffs between the files matched by the 417 * given {@link PathPattern} between two revisions. 418 */ 419 CompletableFuture<List<Change<?>>> getDiff(String projectName, String repositoryName, 420 Revision from, Revision to, PathPattern pathPattern); 421 422 /** 423 * Retrieves the diffs of the files matched by the given path pattern between two {@link Revision}s. 424 * 425 * @return a {@link List} of the {@link Change}s that contain the diffs between the files matched by the 426 * given {@link PathPattern} between two revisions. 427 * 428 * @deprecated Use {@link DiffRequest#get(Revision, Revision)} via 429 * {@link CentralDogmaRepository#diff(PathPattern)}. 430 */ 431 @Deprecated 432 default CompletableFuture<List<Change<?>>> getDiffs(String projectName, String repositoryName, 433 Revision from, Revision to, String pathPattern) { 434 return getDiff(projectName, repositoryName, from, to, toPathPattern(pathPattern)); 435 } 436 437 /** 438 * Retrieves the <em>preview diffs</em>, which are hypothetical diffs generated if the specified 439 * {@link Change}s were successfully pushed to the specified repository. This operation is useful for 440 * pre-checking if the specified {@link Change}s will be applied as expected without any conflicts. 441 * 442 * @return the diffs which would be committed if the specified {@link Change}s were pushed successfully 443 * 444 * @deprecated Use {@link PreviewDiffRequest#get(Revision)} via 445 * {@link CentralDogmaRepository#diff(Change[])}. 446 */ 447 @Deprecated 448 default CompletableFuture<List<Change<?>>> getPreviewDiffs(String projectName, String repositoryName, 449 Revision baseRevision, Change<?>... changes) { 450 return getPreviewDiffs(projectName, repositoryName, baseRevision, ImmutableList.copyOf(changes)); 451 } 452 453 /** 454 * Retrieves the <em>preview diffs</em>, which are hypothetical diffs generated if the specified 455 * {@link Change}s were successfully pushed to the specified repository. This operation is useful for 456 * pre-checking if the specified {@link Change}s will be applied as expected without any conflicts. 457 * This method is equivalent to calling: 458 * <pre>{@code 459 * CentralDogma dogma = ... 460 * dogma.forRepo(projectName, repositoryName) 461 * .diff(changes) 462 * .get(baseRevision); 463 * }</pre> 464 * 465 * @return the diffs which would be committed if the specified {@link Change}s were pushed successfully 466 */ 467 CompletableFuture<List<Change<?>>> getPreviewDiffs(String projectName, String repositoryName, 468 Revision baseRevision, 469 Iterable<? extends Change<?>> changes); 470 471 /** 472 * Pushes the specified {@link Change}s to the repository. 473 * 474 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 475 * 476 * @deprecated Use {@link CommitRequest#push(Revision)} via 477 * {@link CentralDogmaRepository#commit(String, Change...)}. 478 */ 479 @Deprecated 480 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 481 String summary, Change<?>... changes) { 482 return push(projectName, repositoryName, baseRevision, summary, 483 ImmutableList.copyOf(requireNonNull(changes, "changes"))); 484 } 485 486 /** 487 * Pushes the specified {@link Change}s to the repository. 488 * 489 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 490 * 491 * @deprecated Use {@link CommitRequest#push(Revision)} via 492 * {@link CentralDogmaRepository#commit(String, Iterable)}. 493 */ 494 @Deprecated 495 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 496 String summary, Iterable<? extends Change<?>> changes) { 497 return push(projectName, repositoryName, baseRevision, summary, "", Markup.PLAINTEXT, changes); 498 } 499 500 /** 501 * Pushes the specified {@link Change}s to the repository. 502 * 503 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 504 * 505 * @deprecated Use {@link CommitRequest#push(Revision)} via 506 * {@link CentralDogmaRepository#commit(String, Change...)}. 507 */ 508 @Deprecated 509 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 510 String summary, String detail, Markup markup, 511 Change<?>... changes) { 512 return push(projectName, repositoryName, baseRevision, summary, detail, markup, 513 ImmutableList.copyOf(requireNonNull(changes, "changes"))); 514 } 515 516 /** 517 * Pushes the specified {@link Change}s to the repository. 518 * This method is equivalent to calling: 519 * <pre>{@code 520 * CentralDogma dogma = ... 521 * dogma.forRepo(projectName, repositoryName) 522 * .commit(summary, changes) 523 * .detail(detail, markup) 524 * .push(baseRevision); 525 * }</pre> 526 * 527 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 528 */ 529 CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 530 String summary, String detail, Markup markup, 531 Iterable<? extends Change<?>> changes); 532 533 /** 534 * Pushes the specified {@link Change}s to the repository. 535 * 536 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 537 * 538 * @deprecated Use {@link CommitRequest#push(Revision)} via 539 * {@link CentralDogmaRepository#commit(String, Change...)}. 540 */ 541 @Deprecated 542 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 543 Author author, String summary, Change<?>... changes) { 544 return push(projectName, repositoryName, baseRevision, author, summary, ImmutableList.copyOf(changes)); 545 } 546 547 /** 548 * Pushes the specified {@link Change}s to the repository. 549 * 550 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 551 * 552 * @deprecated Use {@link CommitRequest#push(Revision)} via 553 * {@link CentralDogmaRepository#commit(String, Iterable)}. 554 */ 555 @Deprecated 556 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 557 Author author, String summary, 558 Iterable<? extends Change<?>> changes) { 559 return push(projectName, repositoryName, baseRevision, author, summary, "", Markup.PLAINTEXT, changes); 560 } 561 562 /** 563 * Pushes the specified {@link Change}s to the repository. 564 * 565 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 566 * 567 * @deprecated Use {@link CommitRequest#push(Revision)} via 568 * {@link CentralDogmaRepository#commit(String, Change...)}. 569 */ 570 @Deprecated 571 default CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 572 Author author, String summary, String detail, Markup markup, 573 Change<?>... changes) { 574 return push(projectName, repositoryName, baseRevision, author, summary, detail, markup, 575 ImmutableList.copyOf(changes)); 576 } 577 578 /** 579 * Pushes the specified {@link Change}s to the repository. 580 * 581 * @return the {@link PushResult} which tells the {@link Revision} and timestamp of the new {@link Commit} 582 * 583 * @deprecated Use {@link CommitRequest#push(Revision)} via 584 * {@link CentralDogmaRepository#commit(String, Iterable)}. 585 */ 586 @Deprecated 587 CompletableFuture<PushResult> push(String projectName, String repositoryName, Revision baseRevision, 588 Author author, String summary, String detail, Markup markup, 589 Iterable<? extends Change<?>> changes); 590 591 /** 592 * Waits for the files matched by the specified {@code pathPattern} to be changed since the specified 593 * {@code lastKnownRevision}. If no changes were made within 1 minute, the returned 594 * {@link CompletableFuture} will be completed with {@code null}. 595 * 596 * @return the latest known {@link Revision} which contains the changes for the matched files. 597 * {@code null} if the files were not changed for 1 minute since the invocation of this method. 598 * 599 * @deprecated Use {@link WatchFilesRequest#start(Revision)} via 600 * {@link CentralDogmaRepository#watch(PathPattern)}. 601 */ 602 @Deprecated 603 default CompletableFuture<Revision> watchRepository(String projectName, String repositoryName, 604 Revision lastKnownRevision, String pathPattern) { 605 return watchRepository(projectName, repositoryName, lastKnownRevision, toPathPattern(pathPattern), 606 WatchConstants.DEFAULT_WATCH_TIMEOUT_MILLIS, 607 WatchConstants.DEFAULT_WATCH_ERROR_ON_ENTRY_NOT_FOUND); 608 } 609 610 /** 611 * Waits for the files matched by the specified {@code pathPattern} to be changed since the specified 612 * {@code lastKnownRevision}. If no changes were made within the specified {@code timeoutMillis}, the 613 * returned {@link CompletableFuture} will be completed with {@code null}. It is recommended to specify 614 * the largest {@code timeoutMillis} allowed by the server. 615 * 616 * @return the latest known {@link Revision} which contains the changes for the matched files. 617 * {@code null} if the files were not changed for {@code timeoutMillis} milliseconds 618 * since the invocation of this method. 619 * 620 * @deprecated Use {@link CentralDogmaRepository#watch(PathPattern)} and 621 * {@link WatchFilesRequest#start(Revision)}. 622 */ 623 @Deprecated 624 default CompletableFuture<Revision> watchRepository(String projectName, String repositoryName, 625 Revision lastKnownRevision, String pathPattern, 626 long timeoutMillis) { 627 return watchRepository(projectName, repositoryName, lastKnownRevision, toPathPattern(pathPattern), 628 timeoutMillis, WatchConstants.DEFAULT_WATCH_ERROR_ON_ENTRY_NOT_FOUND); 629 } 630 631 /** 632 * Waits for the files matched by the specified {@link PathPattern} to be changed since the specified 633 * {@code lastKnownRevision}. If no changes were made within the specified {@code timeoutMillis}, the 634 * returned {@link CompletableFuture} will be completed with {@code null}. It is recommended to specify 635 * the largest {@code timeoutMillis} allowed by the server. 636 * This method is equivalent to calling: 637 * <pre>{@code 638 * CentralDogma dogma = ... 639 * dogma.forRepo(projectName, repositoryName) 640 * .watch(pathPattern) 641 * .timeoutMillis(timeoutMillis) 642 * .errorOnEntryNotFound(errorOnEntryNotFound) 643 * .start(lastKnownRevision); 644 * }</pre> 645 * 646 * @return the latest known {@link Revision} which contains the changes for the matched files. 647 * {@code null} if the files were not changed for {@code timeoutMillis} milliseconds 648 * since the invocation of this method. {@link EntryNotFoundException} is raised if the 649 * target does not exist. 650 */ 651 CompletableFuture<Revision> watchRepository(String projectName, String repositoryName, 652 Revision lastKnownRevision, PathPattern pathPattern, 653 long timeoutMillis, boolean errorOnEntryNotFound); 654 655 /** 656 * Waits for the file matched by the specified {@link Query} to be changed since the specified 657 * {@code lastKnownRevision}. If no changes were made within 1 minute, the returned 658 * {@link CompletableFuture} will be completed with {@code null}. 659 * 660 * @return the {@link Entry} which contains the latest known {@link Query} result. 661 * {@code null} if the file was not changed for 1 minute since the invocation of this method. 662 * 663 * @deprecated Use {@link WatchRequest#start(Revision)} via {@link CentralDogmaRepository#watch(Query)}. 664 */ 665 @Deprecated 666 default <T> CompletableFuture<Entry<T>> watchFile(String projectName, String repositoryName, 667 Revision lastKnownRevision, Query<T> query) { 668 return watchFile(projectName, repositoryName, lastKnownRevision, query, 669 WatchConstants.DEFAULT_WATCH_TIMEOUT_MILLIS, 670 WatchConstants.DEFAULT_WATCH_ERROR_ON_ENTRY_NOT_FOUND); 671 } 672 673 /** 674 * Waits for the file matched by the specified {@link Query} to be changed since the specified 675 * {@code lastKnownRevision}. If no changes were made within the specified {@code timeoutMillis}, the 676 * returned {@link CompletableFuture} will be completed with {@code null}. It is recommended to specify 677 * the largest {@code timeoutMillis} allowed by the server. 678 * 679 * @return the {@link Entry} which contains the latest known {@link Query} result. 680 * {@code null} if the file was not changed for {@code timeoutMillis} milliseconds 681 * since the invocation of this method. 682 * 683 * @deprecated Use {@link WatchRequest#start(Revision)} via {@link CentralDogmaRepository#watch(Query)}. 684 */ 685 @Deprecated 686 default <T> CompletableFuture<Entry<T>> watchFile(String projectName, String repositoryName, 687 Revision lastKnownRevision, Query<T> query, 688 long timeoutMillis) { 689 return watchFile(projectName, repositoryName, lastKnownRevision, query, 690 timeoutMillis, WatchConstants.DEFAULT_WATCH_ERROR_ON_ENTRY_NOT_FOUND); 691 } 692 693 /** 694 * Waits for the file matched by the specified {@link Query} to be changed since the specified 695 * {@code lastKnownRevision}. If the file does not exist and {@code errorOnEntryNotFound} is {@code true}, 696 * the returned {@link CompletableFuture} will be completed exceptionally with 697 * {@link EntryNotFoundException}. If no changes were made within the specified {@code timeoutMillis}, 698 * the returned {@link CompletableFuture} will be completed with {@code null}. 699 * It is recommended to specify the largest {@code timeoutMillis} allowed by the server. 700 * This method is equivalent to calling: 701 * <pre>{@code 702 * CentralDogma dogma = ... 703 * dogma.forRepo(projectName, repositoryName) 704 * .watch(query) 705 * .timeoutMillis(timeoutMillis) 706 * .errorOnEntryNotFound(errorOnEntryNotFound) 707 * .start(lastKnownRevision); 708 * }</pre> 709 * 710 * @return the {@link Entry} which contains the latest known {@link Query} result. 711 * {@code null} if the file was not changed for {@code timeoutMillis} milliseconds 712 * since the invocation of this method. {@link EntryNotFoundException} is raised if the 713 * target does not exist. 714 */ 715 <T> CompletableFuture<Entry<T>> watchFile(String projectName, String repositoryName, 716 Revision lastKnownRevision, Query<T> query, 717 long timeoutMillis, boolean errorOnEntryNotFound); 718 719 /** 720 * Returns a {@link Watcher} which notifies its listeners when the result of the 721 * given {@link Query} becomes available or changes. e.g: 722 * <pre>{@code 723 * Watcher<JsonNode> watcher = client.fileWatcher("foo", "bar", Query.ofJson("/baz.json")); 724 * 725 * watcher.watch((revision, content) -> { 726 * assert content instanceof JsonNode; 727 * ... 728 * });}</pre> 729 * 730 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(Query)}. 731 */ 732 @Deprecated 733 default <T> Watcher<T> fileWatcher(String projectName, String repositoryName, Query<T> query) { 734 return forRepo(projectName, repositoryName).watcher(query).start(); 735 } 736 737 /** 738 * Returns a {@link Watcher} which notifies its listeners after applying the specified 739 * {@link Function} when the result of the given {@link Query} becomes available or changes. e.g: 740 * <pre>{@code 741 * Watcher<MyType> watcher = client.fileWatcher( 742 * "foo", "bar", Query.ofJson("/baz.json"), 743 * content -> new ObjectMapper().treeToValue(content, MyType.class)); 744 * 745 * watcher.watch((revision, myValue) -> { 746 * assert myValue instanceof MyType; 747 * ... 748 * });}</pre> 749 * 750 * <p>Note that {@link Function} by default is executed by a blocking task executor so that you can 751 * safely call a blocking operation. 752 * 753 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(Query)}. 754 */ 755 @Deprecated 756 <T, U> Watcher<U> fileWatcher(String projectName, String repositoryName, 757 Query<T> query, Function<? super T, ? extends U> function); 758 759 /** 760 * Returns a {@link Watcher} which notifies its listeners after applying the specified 761 * {@link Function} when the result of the given {@link Query} becomes available or changes. e.g: 762 * <pre>{@code 763 * Watcher<MyType> watcher = client.fileWatcher( 764 * "foo", "bar", Query.ofJson("/baz.json"), 765 * content -> new ObjectMapper().treeToValue(content, MyType.class), executor); 766 * 767 * watcher.watch((revision, myValue) -> { 768 * assert myValue instanceof MyType; 769 * ... 770 * });}</pre> 771 * 772 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(Query)}. 773 */ 774 @Deprecated 775 <T, U> Watcher<U> fileWatcher(String projectName, String repositoryName, Query<T> query, 776 Function<? super T, ? extends U> function, Executor executor); 777 778 /** 779 * Returns a {@link Watcher} which notifies its listeners when the specified repository has a new commit 780 * that contains the changes for the files matched by the given {@code pathPattern}. e.g: 781 * <pre>{@code 782 * Watcher<Revision> watcher = client.repositoryWatcher("foo", "bar", "/*.json"); 783 * 784 * watcher.watch(revision -> { 785 * ... 786 * });}</pre> 787 * 788 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(PathPattern)}. 789 */ 790 @Deprecated 791 default Watcher<Revision> repositoryWatcher(String projectName, String repositoryName, String pathPattern) { 792 return forRepo(projectName, repositoryName).watcher(toPathPattern(pathPattern)).start(); 793 } 794 795 /** 796 * Returns a {@link Watcher} which notifies its listeners when the specified repository has a new commit 797 * that contains the changes for the files matched by the given {@code pathPattern}. e.g: 798 * <pre>{@code 799 * Watcher<Map<String, Entry<?>> watcher = client.repositoryWatcher( 800 * "foo", "bar", "/*.json", revision -> client.getFiles("foo", "bar", revision, "/*.json").join()); 801 * 802 * watcher.watch((revision, contents) -> { 803 * ... 804 * });}</pre> 805 * {@link Function} by default is executed by a blocking task executor so that you can safely call a 806 * blocking operation. 807 * 808 * <p>Note that you may get {@link RevisionNotFoundException} during the {@code getFiles()} call and 809 * may have to retry in the above example due to 810 * <a href="https://github.com/line/centraldogma/issues/40">a known issue</a>. 811 * 812 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(PathPattern)}. 813 */ 814 @Deprecated 815 <T> Watcher<T> repositoryWatcher(String projectName, String repositoryName, String pathPattern, 816 Function<Revision, ? extends T> function); 817 818 /** 819 * Returns a {@link Watcher} which notifies its listeners when the specified repository has a new commit 820 * that contains the changes for the files matched by the given {@code pathPattern}. e.g: 821 * <pre>{@code 822 * Watcher<Map<String, Entry<?>> watcher = client.repositoryWatcher( 823 * "foo", "bar", "/*.json", 824 * revision -> client.getFiles("foo", "bar", revision, "/*.json").join(), executor); 825 * 826 * watcher.watch((revision, contents) -> { 827 * ... 828 * });}</pre> 829 * Note that you may get {@link RevisionNotFoundException} during the {@code getFiles()} call and 830 * may have to retry in the above example due to 831 * <a href="https://github.com/line/centraldogma/issues/40">a known issue</a>. 832 * 833 * @param executor the {@link Executor} that executes the {@link Function} 834 * 835 * @deprecated Use {@link WatcherRequest#start()} via {@link CentralDogmaRepository#watcher(PathPattern)}. 836 */ 837 @Deprecated 838 <T> Watcher<T> repositoryWatcher(String projectName, String repositoryName, String pathPattern, 839 Function<Revision, ? extends T> function, Executor executor); 840 841 /** 842 * Returns a {@link CompletableFuture} which is completed when the initial endpoints of this 843 * client are ready. It is recommended to wait for the initial endpoints in order to send the first request 844 * without additional delay. 845 */ 846 CompletableFuture<Void> whenEndpointReady(); 847 }