Fix #122 [NS3] Implement wireless model scenarios with mobility
[nepi.git] / src / nepi / execution / attribute.py
1 #
2 #    NEPI, a framework to manage network experiments
3 #    Copyright (C) 2013 INRIA
4 #
5 #    This program is free software: you can redistribute it and/or modify
6 #    it under the terms of the GNU General Public License as published by
7 #    the Free Software Foundation, either version 3 of the License, or
8 #    (at your option) any later version.
9 #
10 #    This program is distributed in the hope that it will be useful,
11 #    but WITHOUT ANY WARRANTY; without even the implied warranty of
12 #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 #    GNU General Public License for more details.
14 #
15 #    You should have received a copy of the GNU General Public License
16 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 #
18 # Author: Alina Quereilhac <alina.quereilhac@inria.fr>
19
20 ### Attribute Types
21 class Types:
22     String  = "STRING"
23     Bool    = "BOOL"
24     Enumerate    = "ENUM"
25     Double  = "DOUBLE"
26     Integer = "INTEGER"
27
28 ### Attribute Flags
29 class Flags:
30     """ Differents flags to characterize an attribute
31
32     """
33     # Attribute value can not be read (it is hidden to the user) 
34     NoRead    = 1 # 1
35     
36     # Attribute value can not be modified (it is not editable by the user)
37     NoWrite   = 1 << 1 # 2
38     
39     # Attribute value can be modified only before deployment
40     Design  = 1 << 2 # 4
41
42     # Attribute value will be used at deployment time for initial configuration
43     Construct    = 1 << 3 #  8
44
45     # Attribute provides credentials to access resources
46     Credential  = 1 << 4  | Design # 16 + 4
47
48     # Attribute is a filter used to discover resources
49     Filter  = 1 << 5 | Design # 32 + 4
50
51     # Attribute Flag is reserved for internal RM usage (i.e. should be 
52     # transparent to the user)
53     Reserved  = 1 << 6 # 64
54
55
56 class Attribute(object):
57     """
58     .. class:: Class Args :
59
60         An Attribute reflects a configuration parameter for
61         a particular resource. Attributes might be read only or
62         not.
63       
64         :param name: Name of the attribute
65         :type name: str
66
67         :param help: Attribute description
68         :type help: str
69         
70         :param type: The type expected for the attribute value.
71                      Should be one of Attribute.Types .
72         :type type: str
73
74         :param flags: Defines attribute behavior (i.e. whether it is read-only,
75                 read and write, etc). This parameter should take its values from
76                 Attribute.Flags. Flags values can be bitwised.
77         :type flags: hex
78
79         :param default: Default value of the attribute
80         :type default: depends on the type of attribute
81         
82         :param allowed: List of values that the attribute can take. 
83                 This parameter is only meaningful for Enumerate type attributes.
84         :type allowed: list
85         
86         :param range: (max, min) tuple with range of possible values for
87                 attributes.
88                 This parameter is only meaningful for Integer or Double type
89                 attributes.
90         :type range: (int, int) or (float, float)
91         
92         :param set_hook: Function that will be executed whenever a new 
93                 value is set for the attribute.
94         :type set_hook: function
95
96     """
97     def __init__(self, name, help, type = Types.String,
98             flags = None, default = None, allowed = None,
99             range = None, set_hook = None):
100         self._name = name
101         self._help = help
102         self._type = type
103         self._flags = flags or 0
104         self._allowed = allowed
105         self._range = range
106         self._default = self._value = default
107         # callback to be invoked upon changing the 
108         # attribute value
109         self.set_hook = set_hook
110
111     @property
112     def name(self):
113         """ Returns the name of the attribute """
114         return self._name
115
116     @property
117     def default(self):
118         """ Returns the default value of the attribute """
119         return self._default
120
121     @property
122     def type(self):
123         """ Returns the type of the attribute """
124         return self._type
125
126     @property
127     def help(self):
128         """ Returns the help of the attribute """
129         return self._help
130
131     @property
132     def flags(self):
133         """ Returns the flags of the attribute """
134         return self._flags
135
136     @property
137     def allowed(self):
138         """ Returns the allowed value for this attribute """
139         return self._allowed
140
141     @property
142     def range(self):
143         """ Returns the range of the attribute """
144         return self._range
145
146     def has_flag(self, flag):
147         """ Returns true if the attribute has the flag 'flag'
148
149         :param flag: Flag to be checked
150         :type flag: Flags
151         """
152         return (self._flags & flag) == flag
153
154     def get_value(self):
155         """ Returns the value of the attribute """
156         return self._value
157
158     def set_value(self, value):
159         """ Change the value of the attribute after checking the type """
160         valid = True
161
162         if self.type == Types.Enumerate:
163             valid = value in self._allowed
164
165         if self.type in [Types.Double, Types.Integer] and self.range:
166             (min, max) = self.range
167
168             value = float(value)
169
170             valid = (value >= min and value <= max) 
171         
172         valid = valid and self.is_valid_value(value)
173
174         if valid: 
175             if self.set_hook:
176                 # Hook receives old value, new value
177                 value = self.set_hook(self._value, value)
178
179             self._value = value
180         else:
181             raise ValueError("Invalid value %s for attribute %s" %
182                     (str(value), self.name))
183
184     value = property(get_value, set_value)
185
186     def is_valid_value(self, value):
187         """ Attribute subclasses will override this method to add 
188         adequate validation"""
189         return True
190
191     def has_changed(self):
192         """ Returns true if the value has changed from the default """
193         return self.value != self.default