1# Copyright 2018 Google Inc.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14"""Module for the BaseService."""
15
16import abc
17
18
19class BaseService(abc.ABC):
20  """Base class of a Mobly AndroidDevice service.
21
22  This class defines the interface for Mobly's AndroidDevice service.
23  """
24
25  _alias = None
26
27  def __init__(self, device, configs=None):
28    """Constructor of the class.
29
30    The constructor is the only place to pass in a config. If you need to
31    change the config later, you should unregister the service instance
32    from `ServiceManager` and register again with the new config.
33
34    Args:
35      device: the device object this service is associated with.
36      config: optional configuration defined by the author of the service
37        class.
38    """
39    self._device = device
40    self._configs = configs
41
42  @property
43  def alias(self):
44    """String, alias used to register this service with service manager.
45
46    This can be None if the service is never registered.
47    """
48    return self._alias
49
50  @alias.setter
51  def alias(self, alias):
52    self._alias = alias
53
54  @property
55  def is_alive(self):
56    """True if the service is active; False otherwise."""
57
58  def start(self):
59    """Starts the service."""
60
61  def stop(self):
62    """Stops the service and cleans up all resources.
63
64    This method should handle any error and not throw.
65    """
66
67  def pause(self):
68    """Pauses a service temporarily.
69
70    For when the Python service object needs to temporarily lose connection
71    to the device without shutting down the service running on the actual
72    device.
73
74    This is relevant when a service needs to maintain a constant connection
75    to the device and the connection is lost if USB connection to the
76    device is disrupted.
77
78    E.g. a services that utilizes a socket connection over adb port
79    forwarding would need to implement this for the situation where the USB
80    connection to the device will be temporarily cut, but the device is not
81    rebooted.
82
83    For more context, see:
84    `mobly.controllers.android_device.AndroidDevice.handle_usb_disconnect`
85
86    If not implemented, we assume the service is not sensitive to device
87    disconnect, and `stop` will be called by default.
88    """
89    self.stop()
90
91  def resume(self):
92    """Resumes a paused service.
93
94    Same context as the `pause` method. This should resume the service
95    after the connection to the device has been re-established.
96
97    If not implemented, we assume the service is not sensitive to device
98    disconnect, and `start` will be called by default.
99    """
100    self.start()
101
102  def create_output_excerpts(self, test_info):
103    """Creates excerpts of the service's output files.
104
105    [Optional] This method only applies to services with output files.
106
107    For services that generates output files, calling this method would
108    create excerpts of the output files. An excerpt should contain info
109    between two calls of `create_output_excerpts` or from the start of the
110    service to the call to `create_output_excerpts`.
111
112    Use `AndroidDevice#generate_filename` to get the proper filenames for
113    excerpts.
114
115    This is usually called at the end of: `setup_class`, `teardown_test`,
116    or `teardown_class`.
117
118    Args:
119      test_info: RuntimeTestInfo, the test info associated with the scope
120        of the excerpts.
121
122    Returns:
123      List of strings, the absolute paths to the excerpt files created.
124        Empty list if no excerpt files are created.
125    """
126    return []
127