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 com.jcabi.aspects.Loggable;
34 import java.io.IOException;
35 import java.net.URL;
36 import javax.json.Json;
37 import javax.json.JsonObject;
38 import lombok.EqualsAndHashCode;
39 import lombok.ToString;
40
41 /**
42 * Github public key.
43 *
44 * <p>PublicKey implements {@link JsonReadable}, that's how you can get its full
45 * details in JSON format. For example, to get its title,
46 * you get the entire JSON and then gets its element:
47 *
48 * <pre>String title = key.json().getString("title");</pre>
49 *
50 * <p>However, it's better to use a supplementary "smart" decorator, which
51 * automates most of these operations:
52 *
53 * <pre>String title = new PublicKey.Smart(comment).title();</pre>
54 *
55 * @author Carlos Miranda (miranda.cma@gmail.com)
56 * @version $Id: 2390836c67aa091eabff6f410beb186d86671a2a $
57 * @see <a href="https://developer.github.com/v3/users/keys/">Public Keys API</a>
58 */
59 @Immutable
60 @SuppressWarnings("PMD.TooManyMethods")
61 public interface PublicKey extends JsonReadable, JsonPatchable {
62
63 /**
64 * User we're in.
65 *
66 * @return User
67 */
68 User user();
69
70 /**
71 * ID Number of this public key.
72 * @return Public key ID number
73 */
74 int number();
75
76 /**
77 * Smart PublicKey with extra features.
78 * @checkstyle MultipleStringLiterals (500 lines)
79 */
80 @Immutable
81 @ToString
82 @Loggable(Loggable.DEBUG)
83 @EqualsAndHashCode(of = { "key", "jsn" })
84 final class Smart implements PublicKey {
85
86 /**
87 * Encapsulated public key.
88 */
89 private final transient PublicKey key;
90
91 /**
92 * SmartJson object for convenient JSON parsing.
93 */
94 private final transient SmartJson jsn;
95
96 /**
97 * Public ctor.
98 * @param pkey Public key
99 */
100 public Smart(
101 final PublicKey pkey
102 ) {
103 this.key = pkey;
104 this.jsn = new SmartJson(pkey);
105 }
106
107 /**
108 * Get its key value.
109 * @return Value of public key
110 * @throws IOException If there is any I/O problem
111 */
112 public String key() throws IOException {
113 return this.jsn.text("key");
114 }
115
116 /**
117 * Change its value.
118 * @param value Title of public key
119 * @throws IOException If there is any I/O problem
120 */
121 public void key(
122 final String value
123 ) throws IOException {
124 this.key.patch(
125 Json.createObjectBuilder().add("key", value).build()
126 );
127 }
128
129 /**
130 * Get its URL.
131 * @return URL of public key
132 * @throws IOException If there is any I/O problem
133 */
134 public URL url() throws IOException {
135 return new URL(this.jsn.text("url"));
136 }
137
138 /**
139 * Get its title.
140 * @return Title of public key
141 * @throws IOException If there is any I/O problem
142 */
143 public String title() throws IOException {
144 return this.jsn.text("title");
145 }
146
147 /**
148 * Change its title.
149 * @param text Title of public key
150 * @throws IOException If there is any I/O problem
151 */
152 public void title(
153 final String text
154 ) throws IOException {
155 this.key.patch(
156 Json.createObjectBuilder().add("title", text).build()
157 );
158 }
159
160 @Override
161 public JsonObject json() throws IOException {
162 return this.key.json();
163 }
164
165 @Override
166 public void patch(
167 final JsonObject json
168 ) throws IOException {
169 this.key.patch(json);
170 }
171
172 @Override
173 public User user() {
174 return this.key.user();
175 }
176
177 @Override
178 public int number() {
179 return this.key.number();
180 }
181 }
182 }