1 /*
2  * Copyright (C) 2014 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 
17 package android.hardware.cts.helpers.sensoroperations;
18 
19 import android.hardware.cts.helpers.SensorStats;
20 import android.hardware.cts.helpers.SensorTestPlatformException;
21 import android.hardware.cts.helpers.reporting.ISensorTestNode;
22 
23 /**
24  * Base class used by all sensor operations. This allows for complex operations such as chaining
25  * operations together or running operations in parallel.
26  * <p>
27  * Certain restrictions exist for {@link SensorOperation}s:
28  * <p><ul>
29  * <li>{@link #execute(ISensorTestNode)} should only be called once and behavior is undefined for
30  * subsequent calls.
31  * Once {@link #execute(ISensorTestNode)} is called, the class should not be modified. Generally,
32  * there is no synchronization for operations.</li>
33  * <li>{@link #getStats()} should only be called after {@link #execute(ISensorTestNode)}. If it
34  * is called before, the returned value is undefined.</li>
35  * <li>{@link #clone()} may be called any time and should return an operation with the same
36  * parameters as the original.</li>
37  * </ul>
38  */
39 public abstract class SensorOperation {
40     private final SensorStats mStats;
41 
SensorOperation()42     protected SensorOperation() {
43         this(new SensorStats());
44     }
45 
SensorOperation(SensorStats stats)46     protected SensorOperation(SensorStats stats) {
47         mStats = stats;
48     }
49 
50     /**
51      * @return The {@link SensorStats} for the operation.
52      */
getStats()53     public SensorStats getStats() {
54         return mStats;
55     }
56 
57     /**
58      * Executes the sensor operation.
59      * This may throw {@link RuntimeException}s such as {@link AssertionError}s.
60      *
61      * NOTE: the operation is expected to handle interruption by:
62      * - cleaning up on {@link InterruptedException}
63      * - propagating the exception down the stack
64      */
execute(ISensorTestNode parent)65     public abstract void execute(ISensorTestNode parent) throws Exception;
66 
67     /**
68      * @return The cloned {@link SensorOperation}.
69      *
70      * NOTE: The implementation should also clone all child operations, so that a cloned operation
71      * will run with the exact same parameters as the original. The stats should not be cloned.
72      */
clone()73     public abstract SensorOperation clone();
74 
75     /**
76      * Wrapper around {@link SensorStats#addSensorStats(String, SensorStats)}
77      */
addSensorStats(String key, SensorStats stats)78     protected void addSensorStats(String key, SensorStats stats) {
79         getStats().addSensorStats(key, stats);
80     }
81 
82     /**
83      * Wrapper around {@link SensorStats#addSensorStats(String, SensorStats)} that allows an index
84      * to be added. This is useful for {@link SensorOperation}s that have many iterations or child
85      * operations. The key added is in the form {@code key + "_" + index} where index may be zero
86      * padded.
87      */
addSensorStats(String key, int index, SensorStats stats)88     protected void addSensorStats(String key, int index, SensorStats stats) {
89         addSensorStats(String.format("%s_%03d", key, index), stats);
90     }
91 
asTestNode(ISensorTestNode parent)92     protected ISensorTestNode asTestNode(ISensorTestNode parent) {
93         return new SensorTestNode(parent, this);
94     }
95 
96     private class SensorTestNode implements ISensorTestNode {
97         private final ISensorTestNode mParent;
98         private final SensorOperation mOperation;
99 
SensorTestNode(ISensorTestNode parent, SensorOperation operation)100         public SensorTestNode(ISensorTestNode parent, SensorOperation operation) {
101             mParent = parent;
102             mOperation = operation;
103         }
104 
105         @Override
getName()106         public String getName() throws SensorTestPlatformException {
107             return mParent.getName() + "-" + mOperation.getClass().getSimpleName();
108         }
109     }
110 }
111