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
35 /**
36 * Github Git Data References.
37 *
38 * @author Carlos Miranda (miranda.cma@gmail.com)
39 * @version $Id: 2aab40444ef85bcb9ef1e47d2916882ecc122632 $
40 * @since 0.8
41 * @see <a href="https://developer.github.com/v3/git/references/">References API</a>
42 */
43 @Immutable
44 public interface References {
45
46 /**
47 * Owner of them.
48 * @return Repo
49 */
50 Repo repo();
51
52 /**
53 * Creates a reference.
54 * @param ref The name of the fully qualified reference (ie: refs/heads/master).
55 * @param sha The SHA1 value to set this reference to.
56 * @return Reference - The newly created Reference
57 * @throws IOException - If there are any errors.
58 */
59 Reference create(
60 String ref,
61 String sha
62 ) throws IOException;
63
64 /**
65 * Get Reference by identifier.
66 * @param identifier Reference's name.
67 * @return Reference The reference with the given name
68 */
69 Reference get(
70 String identifier
71 );
72
73 /**
74 * Iterates all references.
75 * @return Iterator of references.
76 */
77 Iterable<Reference> iterate();
78
79 /**
80 * Iterates references in sub-namespace.
81 * @param subnamespace Sub-namespace
82 * @return Iterator of references.
83 */
84 Iterable<Reference> iterate(
85 String subnamespace
86 );
87
88 /**
89 * Iterate references under "tags" sub-namespace.
90 * @return Iterator of references.
91 */
92 Iterable<Reference> tags();
93
94 /**
95 * Iterate references under "heads" sub-namespace.
96 * @return Iterator of references.
97 */
98 Iterable<Reference> heads();
99
100 /**
101 * Removes a reference by its identifier.
102 * @param identifier Reference's identifier.
103 * @throws IOException If there is any I/O problem.
104 */
105 void remove(
106 String identifier
107 ) throws IOException;
108 }