Federation 3.2.0 - Model Data api
[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 import org.springframework.web.client.RestClientException;
31
32 import org.acumos.cds.domain.MLPPeer;
33 import org.acumos.cds.domain.MLPCatalog;
34 import org.acumos.cds.domain.MLPSolution;
35 import org.acumos.cds.domain.MLPSolutionRevision;
36 import org.acumos.cds.domain.MLPArtifact;
37 import org.acumos.cds.domain.MLPDocument;
38
39 import org.acumos.federation.client.config.ClientConfig;
40 import org.acumos.federation.client.data.JsonResponse;
41 import org.acumos.federation.client.data.ModelData;
42
43
44 /**
45  * Client for the Federation Server's public (E5) API.  Note that servers
46  * implementing the API may restrict what information they
47  * share with clients.  Servers may refuse access to some clients, may refuse
48  * access to some operations, may restrict what data is visible to clients,
49  * etc., based on their particular policies.  This may result in client
50  * methods returning null, returning lists with reduced numbers of elements, or 
51  * throwing {@link org.springframework.web.client.RestClientException} or its
52  * subclasses.
53  * @see GatewayClient
54  */
55 public class FederationClient extends ClientBase {
56         /**
57          * The base URI for pinging.
58          */
59         public static final String PING_URI = "/ping";
60         /**
61          * The base URI for listing known peers.
62          */
63         public static final String PEERS_URI = "/peers";
64         /**
65          * The base URI for listing visible catalogs.
66          */
67         public static final String CATALOGS_URI = "/catalogs";
68         /**
69          * The base URI for listing catalog solutions.
70          */
71         public static final String SOLUTIONS_URI = "/solutions";
72         /**
73          * The base URI for fetching solution metadata.
74          */
75         public static final String SOLUTION_URI = "/solutions/{solutionId}";
76         /**
77          * The base URI for listing solution revisions.
78          */
79         public static final String REVISIONS_URI = "/solutions/{solutionId}/revisions";
80         /**
81          * The base URI for fetching revision metadata.
82          */
83         public static final String REVISION_URI = "/solutions/{solutionId}/revisions/{revisionId}";
84         /**
85          * The base URI for listing revision artifacts.
86          */
87         public static final String ARTIFACTS_URI = "/solutions/{solutionId}/revisions/{revisionId}/artifacts";
88         /**
89          * The base URI for fetching artifact content.
90          */
91         public static final String ARTIFACT_URI = "/artifacts/{artifactId}/content";
92         /**
93          * The base URI for listing revision documents.
94          */
95         public static final String DOCUMENTS_URI = "/revisions/{revisionId}/documents";
96         /**
97          * The base URI for fetching document content.
98          */
99         public static final String DOCUMENT_URI = "/documents/{documentId}/content";
100         /**
101          * The base URI for registering.
102          */
103         public static final String REGISTER_URI = "/peer/register";
104         /**
105          * The base URI for unregistering.
106          */
107         public static final String UNREGISTER_URI = "/peer/unregister";
108
109         /**
110          * The query for specifying a catalog ID.
111          */
112         public static final String CATID_QUERY = "?catalogId={catalogId}";
113
114         /**
115          * The URI for sending model data from subscriber to supplier.
116          */
117         public static final String MODEL_DATA = "/modeldata";
118
119         /**
120          * Peer Status Code for Active
121          */
122         public static final String PSC_ACTIVE = "AC";
123         /**
124          * Peer Status Code for Renounced
125          */
126         public static final String PSC_RENOUNCED = "RN";
127         /**
128          * Peer Status Code for Requested
129          */
130         public static final String PSC_REQUESTED = "RQ";
131
132         /**
133          * Artifact Type Code for Docker Image
134          */
135         public static final String ATC_DOCKER = "DI";
136
137         /**
138          * Create a Federation Client with the default mapper and resource loader.
139          *
140          * @param target The base URL for the server to be accessed.
141          * @param conf The configuration for certificates and credentials.
142          */
143         public FederationClient(String target, ClientConfig conf) {
144                 this(target, conf, null, null);
145         }
146
147         /**
148          * Create a Federation Client.
149          *
150          * @param target The base URL for the server to be accessed.
151          * @param conf The configuration for certificates and credentials.
152          * @param mapper The object mapper.  If mapper is null, the default
153          *               object mapper is used to read and write JSON.
154          * @param loader The resource loader.  If loader is null, a
155          *               DefaultResourceLoader is created and used.
156          *               The loader is used for accessing the key store
157          *               and trust store for TLS certificates.
158          */
159         public FederationClient(String target, ClientConfig conf, ObjectMapper mapper, ResourceLoader loader) {
160                 super(target, conf, mapper, loader);
161         }
162
163         /**
164          * Check connectivity to the server.
165          *
166          * @return The server's own MLPPeer record.
167          */
168         public MLPPeer ping() {
169                 return handleResponse(PING_URI, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
170         }
171
172         /**
173          * Get a list of the server's peers.
174          *
175          * @return The list of peers.
176          */
177         public List<MLPPeer> getPeers() {
178                 return handleResponse(PEERS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPPeer>>>(){});
179         }
180
181         /**
182          * Request the server to add this client to its list of peers.
183          *
184          * @return The server's own MLPPeer record.
185          */
186         public MLPPeer register() {
187                 return handleResponse(REGISTER_URI, HttpMethod.POST, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
188         }
189
190         /**
191          * Request that the server drop this client from its list of peers.
192          *
193          * @return The server's own MLPPeer record.
194          */
195         public MLPPeer unregister() {
196                 return handleResponse(UNREGISTER_URI, HttpMethod.POST, new ParameterizedTypeReference<JsonResponse<MLPPeer>>(){});
197         }
198
199         /**
200          * @param modelData model (json) data payload
201          * @return json response
202          * @throws RestClientException if remote acumos is not available
203          */
204         public Void receiveModelData(ModelData modelData) throws RestClientException {
205                 return restTemplate.postForObject(MODEL_DATA, modelData, Void.class);
206         }
207
208         /**
209          * Get a list of the server's catalogs.
210          *
211          * @return The list of catalogs (enhanced with their sizes), the peer is willing to share.
212          */
213         public List<MLPCatalog> getCatalogs() {
214                 return handleResponse(CATALOGS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPCatalog>>>(){});
215         }
216
217         /**
218          * Get a list of the solutions in a catalog.
219          *
220          * @param catalogId The ID of the catalog containing the solutions.
221          * @return The list of solutions in the catalog.
222          */
223         public List<MLPSolution> getSolutions(String catalogId) {
224                 return handleResponse(SOLUTIONS_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<List<MLPSolution>>>(){}, catalogId);
225         }
226
227         /**
228          * Get information about a solution.
229          *
230          * @param solutionId The ID of the solution.
231          * @return The solution's metadata, enhanced with its picture and revisions.
232          */
233         public MLPSolution getSolution(String solutionId) {
234                 return handleResponse(SOLUTION_URI, new ParameterizedTypeReference<JsonResponse<MLPSolution>>(){}, solutionId);
235         }
236
237         /**
238          * Get a list of revisions in a solution.
239          *
240          * @param solutionId The ID of the solution.
241          * @return The solution's revisions.
242          */
243         public List<MLPSolutionRevision> getSolutionRevisions(String solutionId) {
244                 return handleResponse(REVISIONS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPSolutionRevision>>>(){}, solutionId);
245         }
246
247         /**
248          * Get information about a revision.
249          *
250          * Note: if catalogId is null, no description or documents will be returned.
251          * @param solutionId The ID of the solution.
252          * @param revisionId The ID of the revision.
253          * @param catalogId The ID of the catalog listing the solution.
254          * @return The revision's metadata, enhanced with its description, artifacts, and documents.
255          */
256         public MLPSolutionRevision getSolutionRevision(String solutionId, String revisionId, String catalogId) {
257                 if (catalogId != null) {
258                         return handleResponse(REVISION_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<MLPSolutionRevision>>(){}, solutionId, revisionId, catalogId);
259                 }
260                 return handleResponse(REVISION_URI, new ParameterizedTypeReference<JsonResponse<MLPSolutionRevision>>(){}, solutionId, revisionId);
261         }
262
263         /**
264          * Get a list of artifacts in a revision.
265          *
266          * @param solutionId The ID of the solution.
267          * @param revisionId The ID of the revision.
268          * @return The revision's artifacts.
269          */
270         public List<MLPArtifact> getArtifacts(String solutionId, String revisionId) {
271                 return handleResponse(ARTIFACTS_URI, new ParameterizedTypeReference<JsonResponse<List<MLPArtifact>>>(){}, solutionId, revisionId);
272         }
273
274         /**
275          * Fetch the content of an artifact.
276          *
277          * Note: artifact content can be large (gigabytes).
278          * @param artifactId The ID of the artifact.
279          * @return An InputStream for retrieving the artifact content.
280          */
281         public InputStream getArtifactContent(String artifactId) {
282                 return download(ARTIFACT_URI, artifactId);
283         }
284
285         /**
286          * List the documents in a revision and catalog.
287          *
288          * @param revisionId The ID of the revision.
289          * @param catalogId The ID of the catalog listing the revision's solution.
290          * @return The revision's documents.
291          */
292         public List<MLPDocument> getDocuments(String revisionId, String catalogId) {
293                 return handleResponse(DOCUMENTS_URI + CATID_QUERY, new ParameterizedTypeReference<JsonResponse<List<MLPDocument>>>(){}, revisionId, catalogId);
294         }
295
296         /**
297          * Fetch the content of a document.
298          *
299          * @param documentId The ID of the document.
300          * @return An InputStream for retrieving the artifact content.
301          */
302         public InputStream getDocumentContent(String documentId) {
303                 return download(DOCUMENT_URI, documentId);
304         }
305 }