1 /**
2 * Copyright (c) 2013-2023, jcabi.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met: 1) Redistributions of source code must retain the above
8 * copyright notice, this list of conditions and the following
9 * disclaimer. 2) Redistributions in binary form must reproduce the above
10 * copyright notice, this list of conditions and the following
11 * disclaimer in the documentation and/or other materials provided
12 * with the distribution. 3) Neither the name of the jcabi.com nor
13 * the names of its contributors may be used to endorse or promote
14 * products derived from this software without specific prior written
15 * permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package com.jcabi.github;
31
32 import com.jcabi.aspects.Immutable;
33 import java.io.IOException;
34 import javax.json.JsonObject;
35
36 /**
37 * Github contents.
38 *
39 * @author Andres Candal (andres.candal@rollasolution.com)
40 * @version $Id: df3df790423272d3a85deeaa1e1610d62db8db82 $
41 * @since 0.8
42 * @see <a href="https://developer.github.com/v3/repos/contents/">Contents API</a>
43 * @checkstyle MultipleStringLiteralsCheck (500 lines)
44 */
45 @Immutable
46 @SuppressWarnings("PMD.AvoidDuplicateLiterals")
47 public interface Contents {
48
49 /**
50 * Owner of them.
51 * @return Repo
52 */
53 Repo repo();
54
55 /**
56 * Get the Readme file of the default branch (usually master).
57 *
58 * @return The Content of the readme file.
59 * @throws IOException If an IO Exception occurs.
60 * @see <a href="http://https://developer.github.com/v3/repos/contents/#get-the-readme">Get the README</a>
61 */
62 Content readme() throws IOException;
63
64 /**
65 * Get the Readme file of the specified branch.
66 *
67 * @param branch The branch name
68 * @return The Content of the readme file.
69 * @throws IOException If an IO Exception occurs.
70 * @see <a href="http://https://developer.github.com/v3/repos/contents/#get-the-readme">Get the README</a>
71 */
72 Content readme(String branch) throws IOException;
73
74 /**
75 * Create new file.
76 * @param content Parameters to create new content
77 * @return Content just created
78 * @throws IOException If there is any I/O problem
79 * @see <a href="https://developer.github.com/v3/repos/contents/#create-a-file">Create a file</a>
80 */
81 Content create(JsonObject content) throws IOException;
82
83 /**
84 * Get the contents of a single file or symbolic link in a repository.
85 * @param path The content path
86 * @param ref The name of the commit/branch/tag.
87 * @return Content fetched
88 * @throws IOException If there is any I/O problem
89 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
90 */
91 Content get(String path, String ref) throws IOException;
92
93 /**
94 * Get the contents of a single file or symbolic link.
95 * in a repository's default branch (usually master).
96 * @param path The content path
97 * @return Content fetched
98 * @throws IOException If there is any I/O problem
99 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
100 */
101 Content get(String path) throws IOException;
102
103 /**
104 * Get the contents of a directory in a repository.
105 * @param path The content path
106 * @param ref The name of the commit/branch/tag. Default: the repository's default branch (usually master)
107 * @return Contents fetched
108 * @throws IOException If there is any I/O problem
109 * @see <a href="https://developer.github.com/v3/repos/contents/#get-contents">Get contents</a>
110 */
111 Iterable<Content> iterate(String path, String ref) throws IOException;
112
113 /**
114 * Removes a file.
115 * @param content Parameters to remove a file
116 * @return RepoCommit referring to this operation
117 * @throws IOException If there is any I/O problem
118 * @see <a href="https://developer.github.com/v3/repos/contents/#delete-a-file">Delete a file</a>
119 */
120 RepoCommit remove(JsonObject content) throws IOException;
121
122 /**
123 * Updates a file.
124 * @param path The content path.
125 * @param json JSON object containing updates to the content.
126 * @return Commit referring to this operation
127 * @throws IOException If any I/O problems occur.
128 * @see <a href="https://developer.github.com/v3/repos/contents/#update-a-file">Update a file</a>
129 */
130 RepoCommit update(String path, JsonObject json) throws IOException;
131
132 /**
133 * Check whether content exists or not.
134 * @param path The content path
135 * @param ref The name of the commit/branch/tag.
136 * @return True if content exists, false otherwise.
137 * @throws IOException If there is any I/O problem
138 */
139 boolean exists(String path, String ref) throws IOException;
140
141 }