Issue 6319: Duration of subscription should be limited
Issue 6321: Define PIM constructs similar Java constructs
Issue 6322: UniqueIdentifier
Issue 6323: Make the names of the operations consistent and more understandable
Issue 6324: Should mention that access control and security is not addressed
Issue 6325: add getConfigurationSet(…) operation
Issue 6326: Introduce operation to get all configuration parameters and their values
Issue 6327: Add mechanism to show which configurationSet (if any) is active
Issue 6328: The specification does not specify how a configuration can be modified
Issue 6329: Operations should return Boolean instead of void
Issue 6330: Assigning ‘null’ to parameters should be avoided
Issue 6331: Exceptions defined should be explained in more details
Issue 6332: Properties
Issue 6333: ConfigurationSets
Issue 6586: ‘Status’ is defined as ‘current status of an SDO
Issue 6587: Configuration interface
Issue 6588: SDOList
Issue 6589: operation getOrganizations() is defined in the SDO interface
Issue 6590: attribute ‘organizations’ of class SDO
Issue 6591: operation setMembers(..)
Issue 6592: introduce operations to get, update/remove individual property of Organisat
Issue 6593: Identifiers for organizations
Issue 6594: Organization description in p2-10
Issue 6595: Organization always has a single instance of OrganizationProperty
Issue 6649: Formatting should be consistent throughout the document.
Issue 6650: Minimum number of services an SDO can provide is not clear
Issue 6651: Definition of SDO not clear
Issue 6652: There is no section about the interface of SDOSystemElement.
Issue 6653: The section overview (section 1.1 p1-1) is confusing
Issue 6654: Structure of OrganizationPropertyList: 2.2.6 p. 2-11
Issue 6655: The descriptions about get/setMembers() are not correct
Issue 6656: What exactly are the properties of a device is not clear
Issue 6657: The description of the parameter ‘properties’ of ServiceProfile not clear
Issue 6658: Description about he SDOService interface
Issue 6663: The parameters defined for the operation setConfigParameter(…)
Issue 6664: differences between a service and a function is not clear.
Issue 6319: Duration of subscription should be limited (sdo-pim-psm-ftf)
Click here for this issue's archive.
Source: Fraunhofer FOKUS (Mr. Raju Nanda Vaidya, nobody)
Nature: Enhancement
Severity: Minor
Summary:
Summary: Duration (or any other time dependent parameter, startTime, notificationInterval) of the subscription should be limited and be specified throughout the specification. Discussion (or Suggestion): The unit of duration (or any other time dependent parameter, startTime, notificationInterval) is specified as 'milliseconds' in the specification. However it is not described everywhere in the specification. The unit of time dependent parameter like 'duration' should be defined everywhere in the specification to eliminate confusion. Duration is defined in Section 2.3.6.1 p2-34 and section2.3.6.2 p2-36 point 5. Proposed resolution: Define 'milliseconds' as unit for all parameters related to time, (eg 'duration' ).
Define all PIM constructs in consistent manner. Most of the PIM constructs are defined as java naming convention (deviceProfile) but some follows the IDL naming convention (enumerated_values). All PIM constructs should follow the same style. Proposed resolution: Define PIM constructs similar Java constructs.
UniqueIdentifier is defined as unique set of string that should be unique within the SDO network domain. ServiceProfiles and other ConfigurationSets are identified by their ‘id’ as well. Identification for these components does not require tobe unique within the whole sdo network domain but should be unique among other ServiceProfiles or ConfigurationSets of the specific SDO. Currently the resource data model defines them as UniqueIdentifier (p2-12 and p2-14) but the operations provided in SDOInterface (p2-18) and ConfigurationInterface (p2-23 removeServiceProfile) defines it as String. Following are the operations: SDOInterface: getServiceProfile(id:String), getServiceRef(id:String) ConfigurationInterface: removeServiceProfile(id:String), removeConfigurationSet(configurationSetID:String), activateConfigurationSet(configID:String) Resource data model and operations in the interface should defined them in similar way, ie. Either UniqueIdentifier or String. Proposed Resolution: Define them as UniqueIdentifier.
Make the names of the operations consistent and more understandable. Operations performing similar task should be named in similar way and the name of the operation should be self explaining as much as possible. Currently some of the operation names are not clear or operations for similar purpose are name in different way. Proposed Resolution: Change - ‘getID()’ to ‘getSDOID()’ - ‘getServiceRef(…)’ to ‘getService(…)’ - ‘getConfigParameter()’ to ‘getConfigurationParameters ()’ - ‘getParameterValue ( … )’ to ‘getConfigurationParameterValue ( … )’ - ‘setConfigParameter (…)’ to ‘setConfigurationParameter (…)’ - ‘getParameterValue(…)’ to ‘getMonitoringParameterValue(…)’ - ‘getCurrentMonitoringStatus()’ to ‘getMonitoringParameterValues()
Should mention that access control and security is not addressed by this submission. The configuration interface provides different operation to access SDO profiles like device or service profiles. These operations must be controlled. However this document does not define how they are controlled. Proposed resolution: Mention in the specification that access control and the security aspects are not addressed by the specification.
Should we add getConfigurationSet(…) operation in configuration interface to get specified configuration set? getConfigurationSets(), addConfigurationSet() and removeConfigurationSet() are used to obtain, add and remove a ConfigurationSet(s). But there is no operation to get specific configuration set. Is it necessary? Proposed resolution: Add the following operation to get specific configuration set getConfigurationSet( configurationSetID: UniqueIdentifier ): ConfigurationSet
Introduce operation to get all configuration parameters and their values? ‘getCurrentMonitoringStatus’ in monitoring interface gets all monitoring parameter and their values. But such operation does not exist in configuration interface. Either remove this operation from the monitoring interface or add similar operation in the configuration interface to make both interfaces consistent.
Add mechanism to show which configurationSet (if any) is active? To know which configuration set is currently active can be very helpful. Currently there is no way of knowing which configuration is active. Proposed resolution: Add an operation in Configuration Interface to return the active configuration set if any. The added operation should handle the following situations: - If the current configuration of the SDO was not set using any predefined ConfigurationSet or - If the configuration of the SDO was changed after it has been active or - If the ConfigurationSet that was used to activate the configuration but was modified later on.
The specification does not specify how a configuration can be modified. No operation to modify existing configuration sets is defined in the configuration interface. A method should be introduced for this purpose or how it can be done should be clearly defined (eg. Existing set is modified if the configuration is stored in the same name.). Possible options: - Add operation to modify stored configurations - Explain that to modify, the configuration set must first be removed and again be stored with the same name but with new values. - Explain that if confirationset is stored with the name that already exists then that configurationSet is modified. This method has disadvantage since same id can be given without knowledge that it already exists. For this, before storing the configurationSet it may need to check if the given id does not exist, which may be operation overhead.
Operations should return Boolean instead of void. Operations that request some action to be performed ((eg. subscribe (data: NotificationSubscription) : void)) does not return anything. Because nothing is returned the requesting SDO will not know if the requested action was carried out successfully or not (eg. if the request for subscription was don’t or not). For this reason Boolean should be returned in such operations. Return Boolean instead of void in such operations.
Assigning ‘null’ to parameters (specially for parameters related to sequence of some parameters, eg: NVList ) should be avoided. Operations should not return null but empty list or raise exception where appropriate. 1. Empty values must be consistently represented throughout the specification. At the moment, empty values are represented by ‘null’ values (see e.g. description of ServiceProfileList on p.2-8; OrganizationList, status on p. 2-9 etc.). For data structures which contain a list of some other data structure (ServiceProfileList) it should not be null but empty list. For data structures like ConfigurationProfile (2-8) or DeviceProfile (p2-9) the data structure cannot be declared as empty. Therefore it can be null but may be it is not necessary to specifically defined it? Only the important point in these case is that exception should be raised and null should not be returned when such data are requested. 2. What an operation should return in every possible condition must be clearly explained. The operations should avoid returning ‘null’. Instead it should raise appropriate exception or in case of a list is requested then an empty list should be returned.
Exceptions defined should be explained in more details to make it more understandable. Some new exceptions are deemed necessary and Exceptions thrown are not consistent. - Exceptions should be explained in more details to make it more understandable. Their description must clearly state its purpose and exactly when they are raised. Example 1: The exception ‘NotAvailable’ described in section 2.3.2.1 p2-18 is not very clear and is confusing with the exception ‘SDONotExists’ (p2-17) which is raised when a client of an SDO cannot reach the target SDO. It is not clear when and who raises this exception. Is it raised when the SDO is accessible but the hardware device the SDO is representing is not accessible? If not then who raises this exception. Example 2: InvalidParameter is raised in operation setDeviceProfile(…) (section 2.3.4.1 p2-23) if the object which is specified by argument does not exist. Explanation should be given to specify what it means by ‘object does not exist’. Note it is described as such in many other operations. - The specification defines four exceptions (section 2.3.2.1 p2-17). These exceptions do not seem to cover all the necessary exceptions that are required. For example, no exceptions are defined to indicate internal errors. Different exceptions are thrown depending upon the operation type. The following are examples where new exceptions may be necessary: Example 1: ‘InvalidParameter’ and ‘NotAvailable’ exceptions are thrown in operation getCurrentMonitoringStatus(). These exceptions does not however reflect any internal errors that can occur during the task execution period (eg. cannot get the variable where the requested data is stored). Example 2: duration of the subscription to monitor SDO properties is not defined yet. But if defined that the subscription duration can be limited (both minimum and maximum) then perhaps new exception is necessary. Example 3: getDeviceProfile (section 2.3.3 p2-19) returns null if DeviceProfile does not exist. It is better to raise some exception rather than to return null. - The specification provides information on exceptions thrown by all operations. But they are not consistent, do not cover all necessary errors in some cases or not well described. All the exceptions thrown in all operations should be discussed in more detail to clarify if they fulfill their purpose in all expect. The following are some examples of described issue: Example 1: operation getID() (section 2.3.3 p2-18 point 1) throws exception InvalidParameter if the requested id of the SDO is null. InvalidParameter according to its definition is raised when a parameter(s) specified in an operation call is invalid (section 2.3.2.1 p 2-18). The definition of InvalidParameter does not describe that it is also raised when requested value is null. Example 2: It should also be noted that in some cases InvalidParameter is raised when the list is empty. This is not in consistent with other similar operation that does not throw this exception when the list is empty and also does not conform to the description of the exception ‘InvalidParameter’.
Different SDOs have different kind of properties. In the SDO RDM properties are described in ‘DevcieProfile’ (p2-11), ‘ServiceProfile’ (p2-12), Status (p2-13), and ‘ConfigurationProfile’ (p2-14). Some properties can be monitored while some can be configured. Currently, from the specification it is not clear which properties can be monitored and which can be configured. The specification should explain the differences between these properties, identify how they are related and discuss the mapping to interfaces better.
ConfigurationSets are described in p2-14 and they are managed by operations in the configuration interface ‘getConfigurationSets ()’, ‘addConfigurationSet(…)’ and ‘removeConfigurationSet(…)’ described in p 2-27 – p2-28. However it is not clear from these descriptions what actually configuration sets are and how they should be used.
‘Status’ is defined as ‘current status of an SDO’ (p2-9, p2-13). Does status represent all properties of an SDO? Or status represent something else? Currently the status contains the name defining the kind of status, and NVList describing the status itself. Why do we need ‘name’ to define status? Does it mean SDO can have more than one status?
The Configuration interface provides operations to ‘set’ or ‘remove’ ‘device’ or ‘service’ profiles (setDeviceProfile(…), addServiceProfile(…), removeDeviceProfile(), removeServiceProfile(…)). We can implement them without problem but the problem is the real implication or the usage of such operations. An SDO may represent a device. We must clearly define in what circumstances do we need to remove the device profile or set the new profile. Similarly an SDO may provide one or more services. How can it provide new services in reality if the device it is representing is the same? How is this new service instantiated? Let’s look at each of these operations in more detail: • setDeviceProfile(…) o Overwrite old DeviceProfile with the new Device Profile. o What else should be done to reflect the changes in the DeviceProfile? • removeDeviceProfile(…) o Removes the existing DeviceProfile o What else should be done to reflect that there is no DeviceProfile? For example if the SDO represents ‘TV’, is this method invoked when real hardware device (‘TV’) is temporarily not available? Moreover, what does it mean when there is no ‘DeviceProfile’ but the SDO represents ‘TV’? Does it still continue to provide services it was providing? • addServiceProfile(…) o Adds new service profile o Instantiate the service An SDO represents a device (eg. ‘TV’) or a service. A ‘TV’ or any other SDOs most probably will not have to provide additional service during its runtime. • removeServiceProfile(…) o stop the service o remove service profile o What else does it need to do? Should it send message to all SDOs that are using this service? Most likely SDO can only internally invoke such operations when required. Other SDO should not be allowed to invoke such operations.
SDOList is first described in section 2.2.5 p2-10 as ‘A list of SDOs that are the members associated with the Organization. But it is not clear from this definition what exactly then is SDO. Does it refer to SDO interface or to the reference of the object representing SDO itself or something else?
The operation getOrganizations() is defined in the SDO interface (see Section 2.3.3). It should be defined in SDOSystemElement. Both SDOs and non-SDOs can participate in an organization as described in Section 2.2.5. That is why the “organizations” attribute is defined in SDOSystemElement (see Section 2.2.3) so that it can be derived to SDOs and non-SDOs. Then, it is logical to define getOrganizations() in SDOSystemElement. In fact, get_organizations() is defined in the SDOSystemElement interface in the proposed PSM (see Section 3.4.1).
As defined in the specification, attribute ‘organizations’ of class SDO is a list of organizations this SDO belongs to (as member or owner). The operation getOrganizations() of the SDO returns this list. Now, it’s not quite clear in what relation the operations addOrganization()/removeOrganization() in Configuration interface stand to this list. Possible solution is: addOrganization( organization : Organization) makes the SDO an owner of the organization that is specified as argument. Then, the implementation of this operation has to append this organization to ‘organization’ list, and call the operation Organization::setOwner(). Then, removeOrganization() lets the SDO to lose this organization, and the organization to lose its owner.
The operation setMembers(..) currently replaces existing members with the given list of members. Should we update it so that the operation can add members to the existing list? For this we need removeMember(s) operation as well.
Currently we can set, get or remove all organization properties. But cannot get, remove or update individual property. Should we introduce operations to get, update or remove individual property of Organization?
Identifiers for organizations can be useful in diverse operations. For example, Configuration::removeOrganization() can have the identifier as argument: removeOrganization (ID: UniqueIdentifier) (see also the functional issue “Parameter for operation removeOrganization(…)”). In addition, these organization IDs can be used by SDO in operations management.
Organization description in p2-10 describes the direction as DependencyType. “direction” attribute is no longer used in Organization (we have changed the attribute’s name from direction to dependency), as shown in page 2-10. So, definitely, we need to change the method names like follows: getDirection(): boolean ? getDependency(): DependencyType setDirection(direction: boolean):void to- setDependency( dependency: DependencyType):void
This method is used to set an OrganizationProperty instance to Organization, and an Organization always has a single instance of OrganizationProperty (it does not have multiple instances of OrganizationProperty), as shown in the class diagram in Appendix B. Therefore, setOrganizationProperty() would be better than addOrganizationProperty(). addOrganizationProperty() implies that multiple instances of OrganizationProperty can be assigned to Organization. Other operations in this specification are named based on this convention. For your reference, see the operations in Configuration interface (setDeviceProfile(), addServiceProfile(), etc.).
Formatting should be consistent throughout the document. E.g.: size of tables in the specification is not the same. Some are larger (p2-3) than it is supposed to be (p2-12). Proposed resolution: All the tables that are bigger should be resized to correct size. All other formatting inconsistencies should be checked and formatted correctly.
Summary: Number of Services an SDO can provide: The minimum number of services an SDO can provide is not clear. An SDO can provide more than one services but it also may not provide any services. According to the Resource Data Model pictured in section 2.2.1, p.2-3, an SDO can have ‘0..n’ ServiceProfile objects; that is, an SDO can have 0..n services. In the table in section 2.2.8 (ServiceProfile) on p. 2-12, in describing ‘id’ it is said: “An SDO can provide one or more services[…]”. This might confuse readers concerning the minimum number of services an SDO can provide. An SDO may provide any number of services
Summary: Definition of SDO not clear: The description of an SDO in Section 2.1 p2-1 is not clear. In Section 2.1 p2-1, an SDO is described as ‘A SDO represents a hardware devices that may be accessed through existing standards or software component and provides information and interfaces for dynamic access by other applications.’ It is not clear what does ‘may be accessed through existing standards’ means. Moreover in this section it does not say about SDOs that may not represent any hardware device. The definition should be modified accordingly.
There is no section about the interface of SDOSystemElement. SDOSystemElement is defined in the sections about the resource data model (Section 2.2.3) and the PSM interface (Section 3.4.1). However, it is not defined in the section about the PIM interface (Section 2.3) where all interfaces are defined. This is inconsistent and confusing.
The section overview (section 1.1 p1-1) is confusing. The section overview (section 1.1 p1-1) only describes the content of the chapter Overview. From its name it sounds like it contains the overview of the whole specification. It is especially confusing since the name of the main chapter is Overview as well. Either rename this section or remove the section and add its content just after the ‘contents’. Proposed resolution: Remove this section and add its content just after the ‘Contents’. Should be noted that section numbering of the following section should be changed accordingly.
Structure of OrganizationPropertyList: 2.2.6 p. 2-11 - OrganizationProperty consists of an NVList, and is itself used as the element type of the OrganizationPropertyList (defined in section 2.3.7 p2-44). What does this structure imply? Since the type OrganizationProperty contains an NVList, where all properties can be stored as name-value pairs, only one element of type Organization is enough to specify all its properties. Operation ‘getOrganizationProperty () : OrganizationProperty’ in Section 2.3.7 p2-44 returns OrganizationProperty but its description defines the return type as OrganizationPropertyList. This structure OrganizationPropertyList is nowhere else used or described except than that it is used in Corba PSM where it is also only declared but not used.
The descriptions about get/setMembers() are not correct. See Sections 2.3.7 (4) and (5). Semantics of setMembers() should be described clearly. See Sections 2.3.7 (5). Need to make it clear how these operation behaves if it is called when an Organization has already had some SDOs in the members attribute. The name of setMembers() implies that the operation replaces the existing SDOs (members) with new ones (i.e. removes the existing ones). However, the table description in Sections 2.3.7 (5) says “SDOs to be added”. This implies that existing ones are preserved and new ones are added. Which semantics do we take? (1) replacing SDOs or (2) adding SDOs? The option (1) is simpler, and (2) is semantically richer. If we go for (2), we need to think if we need to define removeMember() or removeMembers() (this is a technical revision issue, though). Proposed resolution is: replacing SDOs
What exactly are the properties of a device is not clear. It is not clear what device profile properties exactly is (p2-11). Does it contain properties of the device related to its status or they are just detailed specification of the hardware of the device SDO is representing. In other words if these properties - refer to static properties just describing the hardware or - refer to dynamic or static properties which describes its status and that can be configured or monitored. Proposed resolution: update the description to clearly specify that these properties are the properties describing static hardware information.
The description of the parameter ‘properties’ of ServiceProfile is not clear. Parameter ‘properties’ of the ServiceProfile (p2-12) is not clearly defined in the specification. Are these the properties that - describes the service itself (like ontology description of a service) - or define the behavior of the service. These properties can be configured or monitored and any changes of values of these properties will change the service behavior.
Description about he SDOService interface. There is a trivial but important issue in the description about the SDOService interface (Section 2.3.5). SDOService object may implement a service represented by a ServiceProfile object, or may implement multiple services represented by multiple ServiceProfile objects. In other words, SDOService objects and ServiceProfile objects may be related in one-to-one or one-to-many. This is an implementation dependent issue.
The parameters defined for the operation setConfigParameter(…) (Section 2.3.4 (9) p2-25) not correct. The operation is stated to have parameters ‘sdoID:String’, ‘name:String’, and ‘value:any’. However the first parameter ‘sdoID:String’ is not required. It is neither defined in the operation’s description (pp. 2-25 – 2-26) nor in the class diagram (p2-22).
What a function is and what are the differences between a service and a function is not clear. Section 2.2.8 p2-12 defines ServiceProfile using the term ‘function’. Further on a function is defined as ‘a capability of service’. It is not clear what a function is and what is the difference between a service and a function.