Issue 10663: Clarify usage of create_cache operation (data-distribution-rtf)
Source: PrismTech (Mr. Erik Hendriks, erik.hendriks(at)prismtech.com)
Nature: Clarification
Severity: 
Summary: Problem:
The create_cache operation is responsible for creating a DCPS publisher and/or subscriber, depending on the cache usage. If this creation fails a DCPSerror should be thrown, the text should state this.
It should also be stated that a cache is created by default with updated_enabled() returning false, forcing the application to explicitly enable the cache for updates. This prevents that the application immediately starts receiving updates after the enable_all_for_pubsub.

It should also be clarified that the QoS settings on the participant determine if the publisher/subscriber will be created as enabled or disabled entities. IE if the QoS setting for autoenable_created_entities is set to true on the partcipant the Subscriber and Publisher are created in an enabled state, if set to false then both entities will be created in a disabled state.

Solution:
Replace:
Depending on the cache_usage a Publisher, a Subscriber, or both will be created for the unique usage of the Cache. These two objects will be attached to the passed DomainParticipant.

With:
Depending on the cache_usage a Publisher, a Subscriber, or both will be created for the unique usage of the Cache. These two objects will be attached to the passed DomainParticipant. If the creation of the Publisher and/or Subscriber required by the Cache fails a DCPSError is raised. The Cache is created with updates disabled by default (updates_enabled() returning false). The autoenable_created_entities QoS setting of the entity_factory of the passed DomainParticipant determines if the Publisher and/or Subscriber will be created in an enabled or a disabled state. If this QoS setting is set to true then these entities will be created in an enabled state, if set to false then these entities will be created in a disabled state. The Publisher and/or Subscriber themselves will always have their entity_factory.autoenable_created_entities QoS setting set to false, ensuring that DataWriter and DataReader entities are created in a disabled state, this setting may be overridden before the register_all_for_pubsub() call to the created Cache, which will result in the DataWriter and DataReader entities to be created as enabled entities, in this scenario updates will be received from the moment the register_all_for_pubsub is called, but can only be viewed after a call to the enable_all_for_pubsub.
The creation of Topic entities during the register_all_for_pubsub is also slaved to the passed DomainParticipant's entity_factory.autoenable_created_entities QoS setting at the time the register_all_for_pubsub() is called.

Resolution: 
Revised Text: 
Actions taken:
February 12, 2007: received issue
Discussion: 

End of Annotations:=====
ssue ID	PT-DLRL-CLAR-0004
OMG issue ID	
Issue name	Clarify usage of create_cache operation
Status	PENDING SUBMISSION

Problem:
The create_cache operation is responsible for creating a DCPS publisher and/or subscriber, depending on the cache usage. If this creation fails a DCPSerror should be thrown, the text should state this.
It should also be stated that a cache is created by default with updated_enabled() returning false, forcing the application to explicitly enable the cache for updates. This prevents that the application immediately starts receiving updates after the enable_all_for_pubsub.

It should also be clarified that the QoS settings on the participant determine if the publisher/subscriber will be created as enabled or disabled entities. IE if the QoS setting for autoenable_created_entities is set to true on the partcipant the Subscriber and Publisher are created in an enabled state, if set to false then both entities will be created in a disabled state.

Solution:
Replace:
Depending on the cache_usage a Publisher, a Subscriber, or both will be created for the unique usage of the Cache. These two objects will be attached to the passed DomainParticipant.

With:
Depending on the cache_usage a Publisher, a Subscriber, or both will be created for the unique usage of the Cache. These two objects will be attached to the passed DomainParticipant. If the creation of the Publisher and/or Subscriber required by the Cache fails a DCPSError is raised. The Cache is created with updates disabled by default (updates_enabled() returning false). The autoenable_created_entities QoS setting of the entity_factory of the passed DomainParticipant determines if the Publisher and/or Subscriber will be created in an enabled or a disabled state. If this QoS setting is set to true then these entities will be created in an enabled state, if set to false then these entities will be created in a disabled state. The Publisher and/or Subscriber themselves will always have their entity_factory.autoenable_created_entities QoS setting set to false, ensuring that DataWriter and DataReader entities are created in a disabled state, this setting may be overridden before the register_all_for_pubsub() call to the created Cache, which will result in the DataWriter and DataReader entities to be created as enabled entities, in this scenario updates will be received from the moment the register_all_for_pubsub is called, but can only be viewed after a call to the enable_all_for_pubsub.
The creation of Topic entities during the register_all_for_pubsub is also slaved to the passed DomainParticipant.s entity_factory.autoenable_created_entities QoS setting at the time the register_all_for_pubsub() is called.
t