1 /*
2 * SPDX-FileCopyrightText: Copyright (c) 2013-2025 Yegor Bugayenko
3 * SPDX-License-Identifier: MIT
4 */
5 package com.jcabi.github;
6
7 import com.jcabi.aspects.Immutable;
8 import jakarta.json.JsonObject;
9 import java.io.IOException;
10
11 /**
12 * GitHub contents.
13 * @see <a href="https://developer.github.com/v3/repos/contents/">Contents API</a>
14 * @since 0.8
15 * @checkstyle MultipleStringLiteralsCheck (500 lines)
16 */
17 @Immutable
18 @SuppressWarnings("PMD.AvoidDuplicateLiterals")
19 public interface Contents {
20
21 /**
22 * Owner of them.
23 * @return Repo
24 */
25 Repo repo();
26
27 /**
28 * Get the Readme file of the default branch (usually master).
29 * @return The Content of the readme file.
30 * @throws IOException If an IO Exception occurs.
31 * @see <a href="https://developer.github.com/v3/repos/contents/" target="alexandria_uri">http://https://developer.github.com/v3/repos/contents/#get-the-readme">Get the README</a>
32 */
33 Content readme() throws IOException;
34
35 /**
36 * Get the Readme file of the specified branch.
37 * @param branch The branch name
38 * @return The Content of the readme file.
39 * @throws IOException If an IO Exception occurs.
40 * @see <a href="https://developer.github.com/v3/repos/contents/" target="alexandria_uri">http://https://developer.github.com/v3/repos/contents/#get-the-readme">Get the README</a>
41 */
42 Content readme(String branch) throws IOException;
43
44 /**
45 * Create new file.
46 * @param content Parameters to create new content
47 * @return Content just created
48 * @throws IOException If there is any I/O problem
49 * @see <a href="https://developer.github.com/v3/repos/contents/#create-a-file">Create a file</a>
50 */
51 Content create(JsonObject content) throws IOException;
52
53 /**
54 * Get the contents of a single file or symbolic link in a repository.
55 * @param path The content path
56 * @param ref The name of the commit/branch/tag.
57 * @return Content fetched
58 * @throws IOException If there is any I/O problem
59 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
60 */
61 Content get(String path, String ref) throws IOException;
62
63 /**
64 * Get the contents of a single file or symbolic link.
65 * in a repository's default branch (usually master).
66 * @param path The content path
67 * @return Content fetched
68 * @throws IOException If there is any I/O problem
69 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
70 */
71 Content get(String path) throws IOException;
72
73 /**
74 * Get the contents of a directory in a repository.
75 * @param path The content path
76 * @param ref Commit/branch/tag name
77 * @return Contents fetched
78 * @throws IOException If there is any I/O problem
79 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
80 */
81 Iterable<Content> iterate(String path, String ref) throws IOException;
82
83 /**
84 * Removes a file.
85 * @param content Parameters to remove a file
86 * @return RepoCommit referring to this operation
87 * @throws IOException If there is any I/O problem
88 * @see <a href="https://developer.github.com/v3/repos/contents/#delete-a-file">Delete a file</a>
89 */
90 RepoCommit remove(JsonObject content) throws IOException;
91
92 /**
93 * Updates a file.
94 * @param path The content path.
95 * @param json JSON object containing updates to the content.
96 * @return Commit referring to this operation
97 * @throws IOException If any I/O problems occur.
98 * @see <a href="https://developer.github.com/v3/repos/contents/#update-a-file">Update a file</a>
99 */
100 RepoCommit update(String path, JsonObject json) throws IOException;
101
102 /**
103 * Check whether content exists or not.
104 * @param path The content path
105 * @param ref The name of the commit/branch/tag.
106 * @return True if content exists, false otherwise.
107 * @throws IOException If there is any I/O problem
108 */
109 boolean exists(String path, String ref) throws IOException;
110
111 }