Issue 4412: Component port introspection (components-ftf) Source: Mercury Computer Systems (Mr. Frank Pilhofer, fpilhofe@mc.com) Nature: Uncategorized Issue Severity: Summary: The Components::Navigation interface that is implemented by all components provides introspection ("generic navigation") capabilities. There are lots of use cases for introspection, so I wonder why there is introspection for facets, but not for receptacles or event ports. I suggest to add such introspection capabilities. All introspection features should be alike as much as possible for ease of usage. Resolution: see below Revised Text: All the following revisions must be applied to the Chapter 61 of the document ptc/99-10-04. In section 61.4.3.3 page 61-34, replace valuetype FacetDescription { public CORBA::RepositoryId InterfaceID; public FeatureName Name; }; valuetype Facet : FacetDescription { public Object ref; }; typedef sequence<Facet> Facets; typedef sequence<FacetDescription> FacetDescriptions; by valuetype PortDescription { public FeatureName name; public CORBA::RepositoryId type_id; }; valuetype FacetDescription : PortDescription { public Object ref; }; typedef sequence<FacetDescription> FacetDescriptions; In the interface Navigation at page 61-34, replace FacetDescriptions describe_facets(); Facets provide_all_facets(); Facets provide_named_facets (in NameList names) raises (InvalidName); by FacetDescriptions get_all_facets(); FacetDescriptions get_named_facets (in NameList names) raises (InvalidName); At page 61-35, remove the description of the describe_facets operation. In the whole document ptc/99-10-04, remove all occurrences to the describe_facets operations. In the whole document ptc/99-10-04, replace all occurrences of provide_all_facets and provide_named_facets by respectively get_all_facets and get_named_facets. In section 61.5.3 page 61-43, add the following IDL definitions valuetype ReceptacleDescription : PortDescription { public boolean is_multiplex; public ConnectedDescriptions connections; }; typedef sequence<ReceptacleDescription> ReceptacleDescriptions; In the interface Receptacles page 61-43, add the following operations ReceptacleDescriptions get_all_receptacles (); ReceptacleDescriptions get_named_receptacles (in NameList names) raises(InvalidName); Before section 61.6 page 61-44, add the following operation descriptions get_all_receptacles The get_all_receptacles operation returns information about all receptacle ports in the component's inheritance hierarchy as a sequence of ReceptacleDescription values. The order in which these values occur in the sequence is not specified. For components that do not have any receptacles (e.g., a basic component), this operation returns a sequence of length zero. get_named_receptacles The get_named_receptacles operation returns information about all receptacle ports denoted by the names parameter as a sequence of ReceptacleDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for a receptacle in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any receptacles (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. In section 61.6.10 page 61-52, add the following IDL definitions valuetype ConsumerDescription : PortDescription { public EventConsumerBase consumer; }; typedef sequence<ConsumerDescription> ConsumerDescriptions; valuetype EmitterDescription : PortDescription { public EventConsumerBase consumer; }; typedef sequence<EmitterDescription> EmitterDescriptions; valuetype SubscriberDescription { public Cookie ck; public EventConsumerBase consumer; }; typedef sequence<SubscriberDescription> SubscriberDescriptions; valuetype PublisherDescription : PortDescription { public SubscriberDescriptions consumers; }; typedef sequence<PublisherDescription> PublisherDescriptions; In the Events interface page 61-52, add the following operations ConsumerDescriptions get_all_consumers (); ConsumerDescriptions get_named_consumers (in NameList names) raises (InvalidName); EmitterDescriptions get_all_emitters (); EmitterDescriptions get_named_emitters (in NameList names) raises (InvalidName); PublisherDescriptions get_all_publishers (); PublisherDescriptions get_named_publishers (in NameList names) raises (InvalidName); Before section 61.7 page 61-53, add the following operation descriptions get_all_consumers The get_all_consumers operation returns information about all consumer ports in the component's inheritance hierarchy as a sequence of ConsumerDescription values. The order in which these values occur in the sequence is not specified. For components that do not consume any events (e.g., a basic component), this operation returns a sequence of length zero. get_named_consumers The get_named_consumers operation returns information about all consumer ports denoted by the names parameter as a sequence of ConsumerDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for an event sink in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any consumers (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. get_all_emitters The get_all_emitters operation returns information about all emitter ports in the component's inheritance hierarchy as a sequence of EmitterDescription values. The order in which these values occur in the sequence is not specified. For components that do not emit any events (e.g., a basic component), this operation returns a sequence of length zero. get_named_emitters The get_named_emitters operation returns information about all emitter ports denoted by the names parameter as a sequence of EmitterDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for an emitter port in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any emitters (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. get_all_publishers The get_all_publishers operation returns information about all publisher ports in the component's inheritance hierarchy as a sequence of PublisherDescription values. The order in which these values occur in the sequence is not specified. For components that do not publish any events (e.g., a basic component), this operation returns a sequence of length zero. get_named_publishers The get_named_publishers operation returns information about all publisher ports denoted by the names parameter as a sequence of PublisherDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for a publisher port in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any publishers (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. In section 61.11.1 page 61-72, add the following IDL definition valuetype ComponentPortDescription { public FacetDescriptions facets; public ReceptacleDescriptions receptacles; public ConsumerDescriptions consumers; public EmitterDescriptions emitters; public PublisherDescriptions publishers; }; In the CCMObject interface page 61-72, add the following operation ComponentPortDescription get_all_ports (); In section 61.11.1 page 61-73, add the following description before the description of the get_component_def operation get_all_ports The get_all_ports operation returns a value of type ComponentPortDescription containing information about all facets, receptacles, event sinks, emitted events and published events in the component's inheritance hierarchy. The order in which the information occurs in these sequences is not specified. If a component does not offer a port of any type, the associated sequence will have length zero. Actions taken: July 16, 2001: received issue May 13, 2002: closed issue Discussion: The issue is concerned with the limited and incomplete introspection support for components (ref document ptc/99-10-04). While the CCMObject interface inherits from the Navigation interface for introspecting facets (e.g. to get a listing of all available facets) and the Receptacles interface for introspection and manipulation of receptacles, there is no equivalent for event ports. Introspection and type-generic port handling operations are required for dynamic tools. Using information returned from the introspection operations, these tools will be able to manipulate components (e.g. interconnect them) in a generic manner. This resolution describes a set of changes to the Events interface to support generic introspection features for event ports. The types used for facet and receptacle introspection are also updated in order to achieve a consistent interface for all types of ports. (1) Base type A valuetype is added that will serve as base for all port descriptions. This is the same as FacetDescription in the original document, containing the port name and the Repository Id of the port type (i.e. an InterfaceDef for facets and receptacles and an EventDef for emitters, publishers and consumers). valuetype PortDescription { public FeatureName name; public CORBA::RepositoryId type_id; }; (2) Navigation The Facet valuetype is renamed to FacetDescription for consistency. The inheritance from PortDescription is adjusted. valuetype FacetDescription : PortDescription { public Object ref; }; In the Navigation interface, the superfluous operation describe_facets is removed, types are adjusted for consistency, and also for consistency, the provide_ prefix is changed to get_. interface Navigation { Object provide_facet (in FeatureName name) raises (InvalidName); FacetDescriptions get_all_facets (); FacetDescriptions get_named_facets (in NameList names) raises (InvalidName); boolean same_component (in Object ref); }; The semantics of all operations remain the same. (3) Receptacles A new valuetype ReceptacleDescription is introduced to carry information about a receptacle port. valuetype ReceptacleDescription : PortDescription { public boolean is_multiplex; public ConnectedDescriptions connections; }; typedef sequence<ReceptacleDescription> ReceptacleDescriptions; The boolean value is_multiplex is TRUE if the port is a multiplex receptacle (uses multiple), and FALSE otherwise. The connections variable holds a sequence of ConnectionDescription values as already defined. In the Receptacles interface, two operations are added to introspect receptacle ports. interface Receptacles { ReceptacleDescriptions get_all_receptacles (); ReceptacleDescriptions get_named_receptacles (in NameList names) raises(InvalidName); // other operations as before }; The get_all_receptacles operation returns information about all receptacle ports in the component's inheritance hierarchy as a sequence of ReceptacleDescription values. The order in which these values occur in the sequence is not specified. For components that do not have any receptacles (e.g., a basic component), this operation returns a sequence of length zero. The get_named_receptacles operation returns information about all receptacle ports denoted by the names parameter as a sequence of ReceptacleDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for a receptacle in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any receptacles (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. (4) Consumers A new valuetype ConsumerDescription is introduced to carry information about a consumer port. valuetype ConsumerDescription : PortDescription { public EventConsumerBase consumer; }; typedef sequence<ConsumerDescription> ConsumerDescriptions; The consumer variable holds the object reference to the interface of the event sink. In the Events interface, two operations are added to introspect consumes ports. interface Events { ConsumerDescriptions get_all_consumers (); ConsumerDescriptions get_named_consumers (in NameList names) raises (InvalidName); // other operations as before }; The get_all_consumers operation returns information about all consumer ports in the component's inheritance hierarchy as a sequence of ConsumerDescription values. The order in which these values occur in the sequence is not specified. For components that do not consume any events (e.g., a basic component), this operation returns a sequence of length zero. The get_named_consumers operation returns information about all consumer ports denoted by the names parameter as a sequence of ConsumerDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for an event sink in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any consumers (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. (5) Emitters A new valuetype EmitterDescription is introduced to carry information about an emits port. valuetype EmitterDescription : PortDescription { public EventConsumerBase consumer; }; typedef sequence<EmitterDescription> EmitterDescriptions; The consumer variable holds the object reference that is currently connected to the event source, or a nil reference if there is no connection. In the Events interface, two operations are added to introspect emits ports. interface Events { EmitterDescriptions get_all_emitters (); EmitterDescriptions get_named_emitters (in NameList names) raises (InvalidName); // other operations as before }; The get_all_emitters operation returns information about all emitter ports in the component's inheritance hierarchy as a sequence of EmitterDescription values. The order in which these values occur in the sequence is not specified. For components that do not emit any events (e.g., a basic component), this operation returns a sequence of length zero. The get_named_emitters operation returns information about all emitter ports denoted by the names parameter as a sequence of EmitterDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for an emitter port in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any emitters (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. (6) Publishers A new valuetype PublisherDescription is introduced to carry information about a publishes port. Information about a subscriber is held in a new valuetype SubscriberDescription. valuetype SubscriberDescription { public Cookie ck; public EventConsumerBase consumer; }; typedef sequence<SubscriberDescription> SubscriberDescriptions; valuetype PublisherDescription : PortDescription { public SubscriberDescriptions consumers; }; typedef sequence<PublisherDescription> PublisherDescriptions; The consumer variable in SubscriberDescription holds one object reference that is currently connected to the event source, and the Cookie identifying the subscription. In the Events interface, two operations are added to introspect publishes ports. interface Events { PublisherDescriptions get_all_publishers (); PublisherDescriptions get_named_publishers (in NameList names) raises (InvalidName); // other operations as before }; The get_all_publishers operation returns information about all publisher ports in the component's inheritance hierarchy as a sequence of PublisherDescription values. The order in which these values occur in the sequence is not specified. For components that do not publish any events (e.g., a basic component), this operation returns a sequence of length zero. The get_named_publishers operation returns information about all publisher ports denoted by the names parameter as a sequence of PublisherDescription values. The order in which these values occur in the sequence is not specified. If any name in the names parameter is not a valid name for a publisher port in the component's inheritance hierarchy, the operation raises the InvalidName exception. A component that does not provide any publishers (e.g., a basic component) will have no valid name parameter to this operation and thus shall always raise the InvalidName exception. (7) Introspecting all ports A new valuetype ComponentPortDescription is introduced to describe all ports of a component. valuetype ComponentPortDescription { public FacetDescriptions facets; public ReceptacleDescriptions receptacles; public ConsumerDescriptions consumers; public EmitterDescriptions emitters; public PublisherDescriptions publishers; }; A new operation is introduced on the CCMObject interface to retrieve all port descriptions. interface CCMObject : Navigation, Receptacles, Events { ComponentPortDescription get_all_ports (); // other operations as before }; The get_all_ports operation returns a value of type ComponentPortDescription containing information about all facets, receptacles, event sinks, emitted events and published events in the component's inheritance hierarchy. The order in which the information occurs in these sequences is not specified. If a component does not offer a port of any type, the associated sequence will have length zero. End of Annotations:===== Date: Mon, 16 Jul 2001 16:10:24 +0200 From: 520065607613-0001@t-online.de (Frank Pilhofer) To: issues@omg.org Subject: Component port introspection Message-ID: <20010716161024.M515@rose.fpx.de> Reply-To: Frank Pilhofer Mime-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.2.5i X-Sender: 520065607613-0001@t-dialin.net Content-Type: text/plain; charset=us-ascii X-UIDL: *8-e9a4bd93KYd9e:j!! This is a new issue for components-ftf. The Components::Navigation interface that is implemented by all components provides introspection ("generic navigation") capabilities. There are lots of use cases for introspection, so I wonder why there is introspection for facets, but not for receptacles or event ports. I suggest to add such introspection capabilities. All introspection features should be alike as much as possible for ease of usage. Frank -- Frank Pilhofer ........................................... fp@fpx.de A lawyer is someone who writes an eighty-page document and calls it a brief. - Alfred E. Neuman