9d9dc05cb4afb907378c33cf7a4571f22596b5b6
[federation.git] / acumos-fgw-client / src / main / java / org / acumos / federation / client / FederationClient.java
1 /*-
2  * ===============LICENSE_START=======================================================
3  * Acumos
4  * ===================================================================================
5  * Copyright (C) 2019 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
6  * ===================================================================================
7  * This Acumos software file is distributed by AT&T and Tech Mahindra
8  * under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  *      http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * This file is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  * ===============LICENSE_END=========================================================
19  */
20 package org.acumos.federation.client;
21
22 import java.util.List;
23 import java.io.InputStream;
24 import java.net.URI;
25
26 import com.fasterxml.jackson.databind.ObjectMapper;
27 import org.springframework.core.io.ResourceLoader;
28 import org.springframework.core.ParameterizedTypeReference;
29 import org.springframework.http.HttpMethod;
30
31 import org.acumos.cds.domain.MLPPeer;
32 import org.acumos.cds.domain.MLPCatalog;
33 import org.acumos.cds.domain.MLPSolution;
34 import org.acumos.cds.domain.MLPSolutionRevision;
35 import org.acumos.cds.domain.MLPArtifact;
36 import org.acumos.cds.domain.MLPDocument;
37
38 import org.acumos.federation.client.config.ClientConfig;
39 import org.acumos.federation.client.data.JsonResponse;
40
41 /**
42  * Client for the Federation Server's public (E5) API.  Note that servers
43  * implementing the API may restrict what information they
44  * share with clients.  Servers may refuse access to some clients, may refuse
45  * access to some operations, may restrict what data is visible to clients,
46  * etc., based on their particular policies.  This may result in client
47  * methods returning null, returning lists with reduced numbers of elements, or 
48  * throwing {@link org.springframework.web.client.RestClientException} or its
49  * subclasses.
50  * @see GatewayClient
51  */
52 public class FederationClient extends ClientBase {
53         /**
54          * The base URI for pinging.
55          */
56         public static final String PING_URI = "/ping";
57         /**
58          * The base URI for listing known peers.
59          */
60         public static final String PEERS_URI = "/peers";
61         /**
62          * The base URI for listing visible catalogs.
63          */
64         public static final String CATALOGS_URI = "/catalogs";
65         /**
66          * The base URI for listing catalog solutions.
67          */
68         public static final String SOLUTIONS_URI = "/solutions";
69         /**
70          * The base URI for fetching solution metadata.
71          */
72         public static final String SOLUTION_URI = "/solutions/{solutionId}";
73         /**
74          * The base URI for listing solution revisions.
75          */
76         public static final String REVISIONS_URI = "/solutions/{solutionId}/revisions";
77         /**
78          * The base URI for fetching revision metadata.
79          */
80         public static final String REVISION_URI = "/solutions/{solutionId}/revisions/{revisionId}";
81         /**
82          * The base URI for listing revision artifacts.
83          */
84         public static final String ARTIFACTS_URI = "/solutions/{solutionId}/revisions/{revisionId}/artifacts";
85         /**
86          * The base URI for fetching artifact content.
87          */
88         public static final String ARTIFACT_URI = "/artifacts/{artifactId}/content";
89         /**
90          * The base URI for listing revision documents.
91          */
92         public static final String DOCUMENTS_URI = "/revisions/{revisionId}/documents";
93         /**
94          * The base URI for fetching document content.
95          */
96         public static final String DOCUMENT_URI = "/documents/{documentId}/content";
97         /**
98          * The base URI for registering.
99          */
100         public static final String REGISTER_URI = "/peer/register";
101         /**
102          * The base URI for unregistering.
103          */
104         public static final String UNREGISTER_URI = "/peer/unregister";
105
106         /**
107          * The query for specifying a catalog ID.
108          */
109         public static final String CATID_QUERY = "?catalogId={catalogId}";
110
111         /**
112          * Peer Status Code for Active
113          */
114         public static final String PSC_ACTIVE = "AC";
115         /**
116          * Peer Status Code for Renounced
117          */
118         public static final String PSC_RENOUNCED = "RN";
119         /**
120          * Peer Status Code for Requested
121          */
122         public static final String PSC_REQUESTED = "RQ";
123
124         /**
125          * Artifact Type Code for Docker Image
126          */
127         public static final String ATC_DOCKER = "DI";
128
129         /**
130          * Create a Federation Client with the default mapper and resource loader.
131          *
132          * @param target The base URL for the server to be accessed.
133          * @param conf The configuration for certificates and credentials.
134          */
135         public FederationClient(String target, ClientConfig conf) {
136                 this(target, conf, null, null);
137         }
138
139         /**
140          * Create a Federation Client.
141          *
142          * @param target The base URL for the server to be accessed.
143          * @param conf The configuration for certificates and credentials.
144          * @param mapper The object mapper.  If mapper is null, the default
145          *               object mapper is used to read and write JSON.
146          * @param loader The resource loader.  If loader is null, a
147          *               DefaultResourceLoader is created and used.
148          *               The loader is used for accessing the key store
149          *               and trust store for TLS certificates.
150          */
151         public FederationClient(String target, ClientConfig conf, ObjectMapper mapper, ResourceLoader loader) {
152                 super(target, conf, mapper, loader);
153         }
154
155         /**
156          * Check connectivity to the server.
157          *
158          * @return The server's own MLPPeer record.
159          */
160         public MLPPeer ping() {
161                 return handleResponse(PING_URI, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
162         }
163
164         /**
165          * Get a list of the server's peers.
166          *
167          * @return The list of peers.
168          */
169         public List<MLPPeer> getPeers() {
170                 return handleResponse(PEERS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPPeer>>>(){});
171         }
172
173         /**
174          * Request the server to add this client to its list of peers.
175          *
176          * @return The server's own MLPPeer record.
177          */
178         public MLPPeer register() {
179                 return handleResponse(REGISTER_URI, HttpMethod.POST, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
180         }
181
182         /**
183          * Request that the server drop this client from its list of peers.
184          *
185          * @return The server's own MLPPeer record.
186          */
187         public MLPPeer unregister() {
188                 return handleResponse(UNREGISTER_URI, HttpMethod.POST, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
189         }
190
191         /**
192          * Get a list of the server's catalogs.
193          *
194          * @return The list of catalogs (enhanced with their sizes), the peer is willing to share.
195          */
196         public List<MLPCatalog> getCatalogs() {
197                 return handleResponse(CATALOGS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPCatalog>>>(){});
198         }
199
200         /**
201          * Get a list of the solutions in a catalog.
202          *
203          * @param catalogId The ID of the catalog containing the solutions.
204          * @return The list of solutions in the catalog.
205          */
206         public List<MLPSolution> getSolutions(String catalogId) {
207                 return handleResponse(SOLUTIONS_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<List<MLPSolution>>>(){}, catalogId);
208         }
209
210         /**
211          * Get information about a solution.
212          *
213          * @param solutionId The ID of the solution.
214          * @return The solution's metadata, enhanced with its picture and revisions.
215          */
216         public MLPSolution getSolution(String solutionId) {
217                 return handleResponse(SOLUTION_URI, new ParameterizedTypeReference<JsonResponse<MLPSolution>>(){}, solutionId);
218         }
219
220         /**
221          * Get a list of revisions in a solution.
222          *
223          * @param solutionId The ID of the solution.
224          * @return The solution's revisions.
225          */
226         public List<MLPSolutionRevision> getSolutionRevisions(String solutionId) {
227                 return handleResponse(REVISIONS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPSolutionRevision>>>(){}, solutionId);
228         }
229
230         /**
231          * Get information about a revision.
232          *
233          * Note: if catalogId is null, no description or documents will be returned.
234          * @param solutionId The ID of the solution.
235          * @param revisionId The ID of the revision.
236          * @param catalogId The ID of the catalog listing the solution.
237          * @return The revision's metadata, enhanced with its description, artifacts, and documents.
238          */
239         public MLPSolutionRevision getSolutionRevision(String solutionId, String revisionId, String catalogId) {
240                 if (catalogId != null) {
241                         return handleResponse(REVISION_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<MLPSolutionRevision>>(){}, solutionId, revisionId, catalogId);
242                 }
243                 return handleResponse(REVISION_URI, new ParameterizedTypeReference<JsonResponse<MLPSolutionRevision>>(){}, solutionId, revisionId);
244         }
245
246         /**
247          * Get a list of artifacts in a revision.
248          *
249          * @param solutionId The ID of the solution.
250          * @param revisionId The ID of the revision.
251          * @return The revision's artifacts.
252          */
253         public List<MLPArtifact> getArtifacts(String solutionId, String revisionId) {
254                 return handleResponse(ARTIFACTS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPArtifact>>>(){}, solutionId, revisionId);
255         }
256
257         /**
258          * Fetch the content of an artifact.
259          *
260          * Note: artifact content can be large (gigabytes).
261          * @param artifactId The ID of the artifact.
262          * @return An InputStream for retrieving the artifact content.
263          */
264         public InputStream getArtifactContent(String artifactId) {
265                 return download(ARTIFACT_URI, artifactId);
266         }
267
268         /**
269          * List the documents in a revision and catalog.
270          *
271          * @param revisionId The ID of the revision.
272          * @param catalogId The ID of the catalog listing the revision's solution.
273          * @return The revision's documents.
274          */
275         public List<MLPDocument> getDocuments(String revisionId, String catalogId) {
276                 return handleResponse(DOCUMENTS_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<List<MLPDocument>>>(){}, revisionId, catalogId);
277         }
278
279         /**
280          * Fetch the content of a document.
281          *
282          * @param documentId The ID of the document.
283          * @return An InputStream for retrieving the artifact content.
284          */
285         public InputStream getDocumentContent(String documentId) {
286                 return download(DOCUMENT_URI, documentId);
287         }
288 }