Issue 10676: In section 3.1.6.3.7 regarding the ObjectHome clarify some things (data-distribution-rtf) Source: PrismTech (Mr. Erik Hendriks, erik.hendriks(at)prismtech.com) Nature: Clarification Severity: Summary: Problem 1 The description for the name attribute (see issue XXX) needs to be clarified into saying that the name attribute gives the fully qualified name using IDL '::' as seperators (i.e. ObjectHome representing class Foo in module test has as name 'test::Foo'). Solution 1: Replace: o the public name of the application-defined class (name). With: o the public fully qualified name (using IDL seperators '::') of the application-defined class (name). For an ObjectHome representing class Foo in module test it's name becomes 'test::Foo'. Problem 2: The description for the index attribute of the object home needs to specify what the index is in case the home is not yet registered with any Cache. It is our suggestion to make this operation return -1 as value for an ObjectHome which has not yet been registered to any Cache. The description also contains a type, as it talks about index, but it should be registration_index. Solution 2: Replace: o the index under which the ObjectHome has been registered by the Cache (see Cache::register_home operation). With: o the index (registration_index) under which the ObjectHome has been registered by the Cache (see Cache::register_home operation). If the ObjectHome was not yet registered to any Cache then -1 is returned as value. In the IDL description in section 3.2.1.2 on page 3-53 the attribute type of the registration_index needs to be replaced from unsigned_long to long to allow -1 as return value. Replace: readonly attribute unsigned long registration_index; With: readonly attribute long registration_index; In the IDL description in section 3.2.1.2 on page 3-58 regarding the Cache interface description change the return value of the register_home operation from unsigned_long into long: Replace: unsigned long register_home ( in ObjectHome a_home) raises ( PreconditionNotMet); With: long register_home ( in ObjectHome a_home) raises (PreconditionNotMet); Problem 3: The description for the selections and listeners attributes should be in plural, furthermore the attribute names in the description should be bold . Solution 3: Replace: o the list of attached Selection (selections). o the list of attached ObjectListener (listeners). With: o the list of attached Selection objects (selections). o the list of attached ObjectListener objects (listeners). Problem 4: The description for the set_content_filter operation states that it can only be set before the home is registered to a Cache. But this is not correct, it should state that it must be set while the cache the home is registered to (if any) has a pubsub state of INITIAL. As long as the readers have not been created it should not be prohibited to set the content filter. Solution 4: Replace: o set the content_filter for that ObjectHome (set_content_filter). As a content filter is intended to be mapped on the underlying infrastructure it can be set only before the ObjectHome is registered (see Cache::register_home). An attempt to change the filter expression afterwards will raise a PreconditionNotMet. Using an invald filter expression will raise an SQLError. With: o set the content_filter for that ObjectHome (set_content_filter). As a content filter is intended to be mapped on the underlying infrastructure it can be set only if the Cache to which the ObjectHome belongs (if any) has not yet been registered for pubsub. (see Cache::register_all_for_pubsub). An attempt to change the filter expression afterwards will raise a PreconditionNotMet. Using an invald filter expression will raise an SQLError. Problem 5: The description of the deref_all operation talks about the 'most recent' state, but this is not correct. As in 'manual' update mode (using the refresh operation on the Cache) one wants to load the state as known during the last refresh operation, which is not neccesarily the most recent state known in DCPS. Reasoning behind this is that one doesn't want to have inconcistent states within the DLRL, where one object state is significantly 'newer' then other states, especially since 'dereferencing' is only meant to load in a state which is not done at refresh time to gain performance. The deref_all is not meant as a refresh on home level! Solution 5: Replace: o ask to load the most recent state of a DLRL Object into that Object for all objects managed by that home (deref_all). With: o ask to load the last known state (at the time of the last update round) of a DLRL Object into that Object for all objects managed by that home (deref_all). Problem 6: The description about the create_selection operation talks about a SelectionCriteration (second line) where it should talk about a QueryCriterion. In the last line it should clarify that the PreconditionNotMet is raised if the cache it belongs to is still set to INITIAL with relation to the DCPS state as well as if the home does not yet belong to a Cache. Solution 6: Replace: o create a Selection (create_selection). The criterion parameter specifies the SelectionCriterion (either a FilterCriterion or an SelectionCriterion) to be attached to the Selection, the auto_refresh parameter specifies if the Selection has to be refreshed automatically or only on demand (see Selection) and a boolean parameter specifies, when set to TRUE, that the Selection is concerned not only by its member objects but also by their contained ones (concerns_contained_objects); attached SelectionCriterion belong to the Selection that itself belongs to its creating ObjectHome. When creating a Selection while the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. With: o create a Selection (create_selection). The criterion parameter specifies the SelectionCriterion (either a FilterCriterion or an QueryCriterion) to be attached to the Selection, the auto_refresh parameter specifies if the Selection has to be refreshed automatically or only on demand (see Selection) and a boolean parameter specifies, when set to TRUE, that the Selection is concerned not only by its member objects but also by their contained ones (concerns_contained_objects); attached SelectionCriterion belong to the Selection that itself belongs to its creating ObjectHome. When creating a Selection if the ObjectHome does not yet belong to a Cache or while the DCPS State of the Cache that the ObjectHome belongs to is still set to INITIAL, a PreconditionNotMet is raised. Problem 7: The description of the create_unregistered_object should be changed to indicate that only the identity should be set/changed for objects created by this operation. One wants to prevent relations and such to be set on unregistered objects. The only reason this operation exists is to allow an application to set the identity of the object if the object is mapped using predefined mapping rules. In this mode the DLRL cannot determine the keys itself and thus needs user input. Solution 7: Replace the word 'content' on the first line with 'identity'. Problem 8: Clarify the register_object method only takes objects created by the create_unregistered_object method of the same home instance. Solution 8: Replace: o register an object resulting from such a pre-creation (register_object). This operation embeds a logic to derive from the object content a suitable oid; only objects created by create_unregistered_object can be passed as parameter, a PreconditionNotMet is raised otherwise. If the result of the computation leads to an existing oid, an AlreadyExisting exception is raised. Once an object has been registered, the fields that make up its identity (i.e. the fields that are mapped onto the keyfields of the corresponding topics) may not be changed anymore. With: o register an object resulting from such a pre-creation (register_object). This operation embeds a logic to derive from the object content a suitable oid; only objects created by create_unregistered_object (of the same ObjectHome instance) can be passed as parameter, a PreconditionNotMet is raised otherwise. If the result of the computation leads to an existing oid, an AlreadyExisting exception is raised. Once an object has been registered, the fields that make up its identity (i.e. the fields that are mapped onto the keyfields of the corresponding topics) may not be changed anymore. Problem 9: Clarify behavior for the find_object operation if no object with the specified OID can be located. (return NULL). It is not desireable to throw an exception if no object can be found (Notfound) as that is too heavy wait just to report that no object with the specified OID exists.. Solution 9: Replace: o retrieve a DLRL object based on its oid in the in the specified CacheBase (find_object). With: o retrieve a DLRL object based on its oid in the in the specified CacheBase (find_object). If no such object can be located NULL is returned. In the IDL description on page 3-54 in section 3.2.1.2 regarding the ObjectHome replace: ObjectRoot find_object ( in DLRLOid oid, in CacheBase source) raises ( NotFound); With: ObjectRoot find_object ( in DLRLOid oid, in CacheBase source); Problem 10: Clarify the behavior of the get_topic_name operation if the passed attribute is not defined within the home. (it should just return NULL) Solution 10: Replace: o retrieve the name of the topic that contains the value for one attribute(get_topic_name). If the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. With: o retrieve the name of the topic that contains the value for one attribute (get_topic_name), if the attribute is unknown then NULL is returned. If the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. Problem 11: It should be clarified that objects with the state DELETED should not be contained in the get_objects operation of the ObjectHome. The text about ObjectRoot turning into Foo should also be removed, as its already covered by the undefined bit see XXX. Solution 11: Replace: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome (get_objects). For example the type ObjectRoot[ ] will be substituted by a type Foo[ ] in a FooHome. With: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome (get_objects). Objects with the state DELETED are not contained within this list. Problem 12: Remove the text about ObjectRoot becoming Foo in the generated home for the description of the get_created_objects, get_modified_objects, get_deleted_objects. Its already stated with the undefined bit… See XXX Solution 12: Replace: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome and that have been created, modified or deleted during the last refresh operation (get_created_objects, get_modified_objects and get_deleted_objects respectively). The type ObjectRoot[ ] will be substituted by a type Foo[ ] in a FooHome. With: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome and that have been created, modified or deleted during the last refresh operation (get_created_objects, get_modified_objects and get_deleted_objects respectively). Resolution: Revised Text: Actions taken: February 12, 2007: received issue Discussion: In section 3.1.6.3.7 regarding the ObjectHome clarify some things… And remove some typos End of Annotations:===== iler: QUALCOMM Windows Eudora Version 7.0.1.0 Date: Mon, 12 Feb 2007 15:01:52 -0500 To: issues@omg.org, data-distribution-rtf@omg.org From: Juergen Boldt Subject: issue 10676 -- DDS RTF issue X-Virus-Scanned: by amavisd-new-20030616-p10 (Debian) at omg.org This is issue # 10676 From: "Erik Hendriks" In section 3.1.6.3.7 regarding the ObjectHome clarify some things In section 3.1.6.3.7 regarding the ObjectHome clarify some things. And remove some typos Problem 1 The description for the name attribute (see issue XXX) needs to be clarified into saying that the name attribute gives the fully qualified name using IDL '::' as seperators (i.e. ObjectHome representing class Foo in module test has as name 'test::Foo'). Solution 1: Replace: o the public name of the application-defined class (name). With: o the public fully qualified name (using IDL seperators '::') of the application-defined class (name). For an ObjectHome representing class Foo in module test it's name becomes 'test::Foo'. Problem 2: The description for the index attribute of the object home needs to specify what the index is in case the home is not yet registered with any Cache. It is our suggestion to make this operation return -1 as value for an ObjectHome which has not yet been registered to any Cache. The description also contains a type, as it talks about index, but it should be registration_index. Solution 2: Replace: o the index under which the ObjectHome has been registered by the Cache (see Cache::register_home operation). With: o the index (registration_index) under which the ObjectHome has been registered by the Cache (see Cache::register_home operation). If the ObjectHome was not yet registered to any Cache then -1 is returned as value. In the IDL description in section 3.2.1.2 on page 3-53 the attribute type of the registration_index needs to be replaced from unsigned_long to long to allow -1 as return value. Replace: readonly attribute unsigned long registration_index; With: readonly attribute long registration_index; In the IDL description in section 3.2.1.2 on page 3-58 regarding the Cache interface description change the return value of the register_home operation from unsigned_long into long: Replace: unsigned long register_home ( in ObjectHome a_home) raises ( PreconditionNotMet); With: long register_home ( in ObjectHome a_home) raises (PreconditionNotMet); Problem 3: The description for the selections and listeners attributes should be in plural, furthermore the attribute names in the description should be bold . Solution 3: Replace: o the list of attached Selection (selections). o the list of attached ObjectListener (listeners). With: o the list of attached Selection objects (selections). o the list of attached ObjectListener objects (listeners). Problem 4: The description for the set_content_filter operation states that it can only be set before the home is registered to a Cache. But this is not correct, it should state that it must be set while the cache the home is registered to (if any) has a pubsub state of INITIAL. As long as the readers have not been created it should not be prohibited to set the content filter. Solution 4: Replace: o set the content_filter for that ObjectHome (set_content_filter). As a content filter is intended to be mapped on the underlying infrastructure it can be set only before the ObjectHome is registered (see Cache::register_home). An attempt to change the filter expression afterwards will raise a PreconditionNotMet. Using an invald filter expression will raise an SQLError. With: o set the content_filter for that ObjectHome (set_content_filter). As a content filter is intended to be mapped on the underlying infrastructure it can be set only if the Cache to which the ObjectHome belongs (if any) has not yet been registered for pubsub. (see Cache::register_all_for_pubsub). An attempt to change the filter expression afterwards will raise a PreconditionNotMet. Using an invald filter expression will raise an SQLError. Problem 5: The description of the deref_all operation talks about the 'most recent' state, but this is not correct. As in 'manual' update mode (using the refresh operation on the Cache) one wants to load the state as known during the last refresh operation, which is not neccesarily the most recent state known in DCPS. Reasoning behind this is that one doesn't want to have inconcistent states within the DLRL, where one object state is significantly 'newer' then other states, especially since 'dereferencing' is only meant to load in a state which is not done at refresh time to gain performance. The deref_all is not meant as a refresh on home level! Solution 5: Replace: o ask to load the most recent state of a DLRL Object into that Object for all objects managed by that home (deref_all). With: o ask to load the last known state (at the time of the last update round) of a DLRL Object into that Object for all objects managed by that home (deref_all). Problem 6: The description about the create_selection operation talks about a SelectionCriteration (second line) where it should talk about a QueryCriterion. In the last line it should clarify that the PreconditionNotMet is raised if the cache it belongs to is still set to INITIAL with relation to the DCPS state as well as if the home does not yet belong to a Cache. Solution 6: Replace: o create a Selection (create_selection). The criterion parameter specifies the SelectionCriterion (either a FilterCriterion or an SelectionCriterion) to be attached to the Selection, the auto_refresh parameter specifies if the Selection has to be refreshed automatically or only on demand (see Selection) and a boolean parameter specifies, when set to TRUE, that the Selection is concerned not only by its member objects but also by their contained ones (concerns_contained_objects); attached SelectionCriterion belong to the Selection that itself belongs to its creating ObjectHome. When creating a Selection while the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. With: o create a Selection (create_selection). The criterion parameter specifies the SelectionCriterion (either a FilterCriterion or an QueryCriterion) to be attached to the Selection, the auto_refresh parameter specifies if the Selection has to be refreshed automatically or only on demand (see Selection) and a boolean parameter specifies, when set to TRUE, that the Selection is concerned not only by its member objects but also by their contained ones (concerns_contained_objects); attached SelectionCriterion belong to the Selection that itself belongs to its creating ObjectHome. When creating a Selection if the ObjectHome does not yet belong to a Cache or while the DCPS State of the Cache that the ObjectHome belongs to is still set to INITIAL, a PreconditionNotMet is raised. Problem 7: The description of the create_unregistered_object should be changed to indicate that only the identity should be set/changed for objects created by this operation. One wants to prevent relations and such to be set on unregistered objects. The only reason this operation exists is to allow an application to set the identity of the object if the object is mapped using predefined mapping rules. In this mode the DLRL cannot determine the keys itself and thus needs user input. Solution 7: Replace the word 'content' on the first line with 'identity'. Problem 8: Clarify the register_object method only takes objects created by the create_unregistered_object method of the same home instance. Solution 8: Replace: o register an object resulting from such a pre-creation (register_object). This operation embeds a logic to derive from the object content a suitable oid; only objects created by create_unregistered_object can be passed as parameter, a PreconditionNotMet is raised otherwise. If the result of the computation leads to an existing oid, an AlreadyExisting exception is raised. Once an object has been registered, the fields that make up its identity (i.e. the fields that are mapped onto the keyfields of the corresponding topics) may not be changed anymore. With: o register an object resulting from such a pre-creation (register_object). This operation embeds a logic to derive from the object content a suitable oid; only objects created by create_unregistered_object (of the same ObjectHome instance) can be passed as parameter, a PreconditionNotMet is raised otherwise. If the result of the computation leads to an existing oid, an AlreadyExisting exception is raised. Once an object has been registered, the fields that make up its identity (i.e. the fields that are mapped onto the keyfields of the corresponding topics) may not be changed anymore. Problem 9: Clarify behavior for the find_object operation if no object with the specified OID can be located. (return NULL). It is not desireable to throw an exception if no object can be found (Notfound) as that is too heavy wait just to report that no object with the specified OID exists.. Solution 9: Replace: o retrieve a DLRL object based on its oid in the in the specified CacheBase (find_object). With: o retrieve a DLRL object based on its oid in the in the specified CacheBase (find_object). If no such object can be located NULL is returned. In the IDL description on page 3-54 in section 3.2.1.2 regarding the ObjectHome replace: ObjectRoot find_object ( in DLRLOid oid, in CacheBase source) raises ( NotFound); With: ObjectRoot find_object ( in DLRLOid oid, in CacheBase source); Problem 10: Clarify the behavior of the get_topic_name operation if the passed attribute is not defined within the home. (it should just return NULL) Solution 10: Replace: o retrieve the name of the topic that contains the value for one attribute(get_topic_name). If the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. With: o retrieve the name of the topic that contains the value for one attribute (get_topic_name), if the attribute is unknown then NULL is returned. If the DCPS State of the Cache is still set to INITIAL, a PreconditionNotMet is raised. Problem 11: It should be clarified that objects with the state DELETED should not be contained in the get_objects operation of the ObjectHome. The text about ObjectRoot turning into Foo should also be removed, as its already covered by the undefined bit see XXX. Solution 11: Replace: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome (get_objects). For example the type ObjectRoot[ ] will be substituted by a type Foo[ ] in a FooHome. With: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome (get_objects). Objects with the state DELETED are not contained within this list. Problem 12: Remove the text about ObjectRoot becoming Foo in the generated home for the description of the get_created_objects, get_modified_objects, get_deleted_objects. Its already stated with the undefined bit. See XXX Solution 12: Replace: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome and that have been created, modified or deleted during the last refresh operation (get_created_objects, get_modified_objects and get_deleted_objects respectively). The type ObjectRoot[ ] will be substituted by a type Foo[ ] in a FooHome. With: o obtain from a CacheBase a (typed) list of all objects that match the type of the selected ObjectHome and that have been created, modified or deleted during the last refresh operation (get_created_objects, get_modified_objects and get_deleted_objects respectively). Juergen Boldt Director, Member Services Object Management Group 140 Kendrick St Building A Suite 300 Needham, MA 02494 USA tel: +1 781 444 0404 x 132 fax: +1 781 444 0320 email: juergen@omg.org www.omg.org