1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.android.tradefed.cluster;
17 
18 import com.android.tradefed.config.GlobalConfiguration;
19 import com.android.tradefed.config.IConfiguration;
20 
21 import org.json.JSONException;
22 
23 import java.io.IOException;
24 import java.util.List;
25 
26 /** An interface for interacting with the TFC backend. */
27 public interface IClusterClient {
28     /**
29      * The unique configuration object type name. Used to retrieve the singleton instance from the
30      * {@link GlobalConfiguration}.
31      *
32      * @see IConfiguration#getConfigurationObject(String)
33      */
34     public static final String TYPE_NAME = "cluster_client";
35 
36     /**
37      * Get a {@link IClusterEventUploader} that can be used to upload {@link ClusterCommandEvent}s.
38      */
getCommandEventUploader()39     public IClusterEventUploader<ClusterCommandEvent> getCommandEventUploader();
40 
41     /** Get a {@link IClusterEventUploader} that can be used to upload {@link ClusterHostEvent}s. */
getHostEventUploader()42     public IClusterEventUploader<ClusterHostEvent> getHostEventUploader();
43 
44     /**
45      * Lease {@link ClusterCommand} for the give host.
46      *
47      * @param clusterId cluster id for the host
48      * @param hostname hostname
49      * @param devices deviceInfos the host has
50      * @param nextClusterIds a list of next cluster IDs to lease commands from.
51      * @param maxTasksTolease the max number of tasks that can current be leased
52      * @return a list of {@link ClusterCommand}
53      * @throws JSONException
54      */
leaseHostCommands( final String clusterId, final String hostname, final List<ClusterDeviceInfo> devices, final List<String> nextClusterIds, final int maxTasksTolease)55     public List<ClusterCommand> leaseHostCommands(
56             final String clusterId,
57             final String hostname,
58             final List<ClusterDeviceInfo> devices,
59             final List<String> nextClusterIds,
60             final int maxTasksTolease)
61             throws JSONException;
62 
63     /**
64      * Get {@link TestEnvironment} for a request.
65      *
66      * @param requestId
67      * @return a {@link TestEnvironment} object.
68      * @throws IOException
69      * @throws JSONException
70      */
getTestEnvironment(final String requestId)71     public TestEnvironment getTestEnvironment(final String requestId)
72             throws IOException, JSONException;
73 
74     /**
75      * Get {@link TestResource}s for a request.
76      *
77      * @param requestId
78      * @return a list of {@link TestResource}.
79      * @throws IOException
80      * @throws JSONException
81      */
getTestResources(final String requestId)82     public List<TestResource> getTestResources(final String requestId)
83             throws IOException, JSONException;
84 
getTestContext(final String requestId, final String commandId)85     public TestContext getTestContext(final String requestId, final String commandId)
86             throws IOException, JSONException;
87 
updateTestContext( final String requestId, final String commandId, TestContext testContext)88     public void updateTestContext(
89             final String requestId, final String commandId, TestContext testContext)
90             throws IOException, JSONException;
91 
92     /**
93      * Get the command status of a cluster command (the state and the cancel reason if canceled).
94      *
95      * @param requestId cluster request ID
96      * @param commandId cluster command ID
97      * @return a ClusterCommandStatus that represents the state and the cancel reason if the command
98      *     is canceled. The state is {@link ClusterCommand.State#UNKNOWN} if it could not be
99      *     determined.
100      */
getCommandStatus(String requestId, String commandId)101     public default ClusterCommandStatus getCommandStatus(String requestId, String commandId) {
102         ClusterCommand.State state = getCommandState(requestId, commandId);
103         return new ClusterCommandStatus(state, "");
104     }
105 
106     /**
107      * Determine the state of a cluster command.
108      *
109      * @param requestId cluster request ID
110      * @param commandId cluster command ID
111      * @return cluster command's state, or {@link ClusterCommand.State#UNKNOWN} if state could not
112      *     be determined
113      */
getCommandState(String requestId, String commandId)114     public ClusterCommand.State getCommandState(String requestId, String commandId);
115 }
116