Dear All,
This is the final call for BuilderServices. I will put it up on the voting machine before Wednesday (28Nov01). A few changes have been made. You can view this in html at this which may be a little easier to read. There are essentially three changes to what I sent out before:
getLocalComponentClasses so that
we have some way of identifying what components are in the pallet
from which applications can be built. This is obtained through the
BuilderServices interface method:
ComponentRepository getComponentRepository This is based on
suggestions by both Steve and Dennis (both should make sure this
incarnation is suitable).setXProperties() methods to go along with the getXProperties()
methods in the original.Everything is specified in SIDL. I will probably provide C++ and Java versions just to keep the neanderthals on the same page.
Cheers,
-Rob
Details follow:
Three methods have been added to the BuilderServices interface pairing a
setXProperties() with each getXProperties() each uses a TypeMap:
The justification for this is just completeness. If the BuilderServices interface allows framework-like actions to be performed by an outside entity, it probably should be able to set as well as get properties. As part of the specification, a caveat is stipulated that the implementing framework may lock any property it deems critical to its own operation just as getXProperties may not expose all possible properties that the framework has set.
If you recall I had a list of questions that seemed to be small inconsistencies and sought resolution from you guys. I was underwhelmed by the response. Undaunted I questioned the people most likely to know the answer and/or most likely to have an opinion (not always do these two things coincide). The previous questions were resolved in the following way:
Question: array<ComponentID,1> getComponentIDs method in
BuilderService throws a CCAException. Why?
Answer: The only justification for this I could find for
this was from Ben: "you could have run out of memory". This
means that there would never be a method that we would specify
that would not throw a CCAException. This is because any
method without an exception would not be able to rely on
malloc to get its job done and is tantamount to specifying
the implementation as well as the interface. Steve Parker adds
that " almost always when malloc fails so will the ability to
throw exceptions." Result: getComponentIDs() will not throw a
CCAException.
Question: I beg dispensation from the CCA name police. I re-renamed the
Framework interface back to gov.cca.AbstractFramework.
It was and is very hard to distinguish references between the underlying
framework implementation and the abstract interface. Just in
writing the little documentation here, it became obvious to me
that it was very confusing to refer to the implementation and the
interface as "framework."
Answer: I will keep it AbstractFramework. It causes to
many problems in discussions about generic frameworks and an
interface named Framework .
Question: It seemed to me that
AbstractFramework createEmptyFramework
method in AbstractFramework might not work in every
framework imaginable so I said that an exception could be thrown from
that method if the underlying framework "felt like it."
Answer: Dennis concurred so I left it in. This is just a behavioral point and does not affect the syntax.
All of this is the result of notes and emails from myself, Dennis
( see below ) , and Boyana
( see below ). When there
was doubt about the many conflicts, I chose Boyana, since she seemed
the most reliable of the three. Here I have assumed complete
acceptance of Steve Parker's TypeMap class and the new
ComponentID both proposed separately and TypeMap has passed.
Interface BuilderService is a Port implemented by a CCA
compliant framework for the purpose of composing components into
applications in a standard way. It is meant to expose the
Component creation and composition functionality without the
specific framework implementation. This interface is expected to be
useful for rapid application development in a scripting language.
Other uses are generic application development environments for CCA
applications.
ComponentID createInstance(in string className, in string instanceName,in TypeMap environment) throws CCAExceptionCreates an instance of a CCA component
of the type defined by the string className. The string
classname uniquely defines the "type" of the component, e.g.
doe.cca.linearsolvers.gaussian_elminiation.
It has instance name given by the string instanceName (which may
be null). If the Component className is unknown, or
if the instanceName has already been used, a CCAException
is thrown.
array<ComponentID,1> getComponentIDs()Return a ComponentID for each component currently created.
TypeMap getComponentProperties(in ComponentID cid) throws CCAExceptionReturn the public properties associated with the component
referred to by ComponentID. Throws a CCAException if
the ComponentID is invalid.
void setComponentProperties(in ComponentID cid, TypeMap map) throws CCAExceptionCauses the framework implementation to associate the given properties with the component designated by cid. Throws a CCAException if cid is invalid or if this property is locked by the underlying framework.
ComponentID getDeserialization(in string s) throws CCAExceptionReturns a ComponentID from the string produced by
ComponentID method getSerialization(). Throws a
CCAException if the string does not represent the
appropriate serialization of a ComponentID for the
underlying framework.
ComponentID getComponentID( in string componentInstanceName ) throws CCAExceptionGets the unique ComponentID for the instance name of the
component. Throws a CCAException if there is no component
matching the given componentInstanceName.
void destroyInstance(in ComponentID todie, float timeout ) throws CCAExceptionEliminate the Component instance, identified by todie,
from the scope of the framework. Throws a CCAException
under the following conditions:
ComponentRepository getComponentRepository()Returns the default ComponentRepository for this framework.
array<string, 1> getProvidesPorts(in ComponentID cid) throws CCAExceptionGet the provides Port's instance names for the component
indicated by cid. Throws CCAException if cid
refers to an invalid component. Throws CCAException if
cid refers to an invalid component.
array<string,1> getUsesPorts(in ComponentID cid) throws CCAExceptionGet the uses Port's instance names for the component
indicated by cid. Throws CCAException if cid
refers to an invalid component. Throws CCAException if
cid refers to an invalid component.
TypeMap getPortProperties(in ComponentID cid, in string portname) throws CCAExceptionReturns the public properties pertaining to the Port
instance portname on the component referred to by cid.
Throws CCAException when any one of the following conditions
occur:
Port on the
component indicated by cid.void setPortProperties(in ComponentID cid, in string portname, in TypeMap map) throws CCAExceptionAssociates the properties given in map with the port indicated by portname belonging to the component referred to by cid. Throws a CCAException if either cid or portname are invalid, or if this property is locked by the underlying framework.
ConnectionID connect(in ComponentID user, in string usingPortName,in ComponentID provider, in string providingPortName) throws CCAExceptionCreates a connection between component user and component
provider. Throws a CCAException when any one of the
following conditions occur:
Port on their respective components.Array<ConnectionID, 1> getConnectionIDs(Array<ComponentID, 1> componentList) throws CCAExceptionReturns a list of connections that may be referred to by the
ConnectionID opaque handle. This will return all
connections involving components in componentList. This
means that ConnectionID's will be returned even if only one
of the participants in the connection appears in
componentList. Throws a CCAException if any component
in componentList is invalid.
TypeMap getConnectionProperties(in ConnectionID id)Returns the properties for the given connection.
void setConnectionProperties(in ConnectionID id, TypeMap map) throws CCAExceptionAssociate the properties given in map with the connection indicated by id. Throws a CCAException if id is invalid, or if this property is locked by the underlying framework.
void disconnect(in ConnectionID id, in float timeout) throws CCAExceptionDisconnect the connection indicated by id before the
indicated timeout in secs. Upon successful
completion, the ConnectionID referenced by id becomes
invalid. Throws a CCAException when any one of the following
conditions occur:
ConnectionID.disconnect() was invoked, it remains valid.void disconnectAll(in ComponentID id1, in ComponentID id2, in float timeout) throws CCAExceptionRemove all connections between components id1 and id2
within the period of timeout secs. If id2 is null,
Then all connections to id1 within the period of
timeout secs are removed. Throws a CCAException when
any one of the following conditions occur:
ComponentID.(({ConnectionID})) describes a CCA connection. A connection is
when one component provides a (({Port})) that another component
advertises for and uses. The components are referred to by their
opaque ComponentID references and the (({Port}))'s are referred to
by their (({string})) instance names.
ComponentID getProvider() throws CCAExceptionReturn the ComponentID of the component that has provided
the Port for this connection. Throws a CCAException
if the underlying connection is no longer valid.
ComponentID getUser() throws CCAExceptionReturn the ComponentID of the component that is using the
provided Port. Throws a CCAException
if the underlying connection is no longer valid.
string getProvidesPortName() throws CCAExceptionReturn the instance name of the provided Port. Throws a
CCAException if the underlying connection is no longer
valid.
string getUsesPortName() throws CCAExceptionReturn the instance name of the Port registered for use in this
connection. Throws a CCAException if the underlying
connection is no longer valid.
This is an interface presented by a CCA-compliant framework to access
its application framing capabilities. Most of the manipulation of the
underlying framework is expected to be be done with the
gov.cca.BuilderService Port. This class exists as a sort
of bootstrap to get a Services object necessary to retreive
Port's, including BuilderService, from the underlying framework.
How the interface and the underlying framework is created is entirely
unspecified and is up to the devices of the programmer and the
framework provider.
TypeMap createTypeMap()Create an empty TypeMap. Presumably this would be used in
an ensuing call to getServices() .
Services getServices(in string selfInstanceName, in string selfClassName, in TypeMap selfProperties) throws CCAExceptionRetrieve a Services handle to the underlying framework.
This interface effectively causes the calling program to
appear as the image of a component inside the framework.
selfInstanceName refers to the Component instance name
and selfClassName refers to the Component type for the
calling program. selfProperties (which can be null)
refers to the properties of the component image. This method may
be called any number of times with different arguments, creating a
new component image each time. Throws a CCAException in the
event that selfInstanceName is already in use by another
component.
void releaseServices(in Services svc) throws CCAExceptionIndicate that the Services handle is no longer needed by the
caller and that the reference to its component image is deleted
from the context of the underlying framework. This invalidates
any ComponentID's or ConnectionID's associated with
this calling program's component image. Throws CCAException
if the Services handle has already been released or is otherwise
rendered invalid.
void shutdownFramework() throws CCAExceptionTell the framework it is no longer needed and to clean up after
itself. Throws a CCAException if the framework has already
been shutdown.
AbstractFramework createEmptyFramework() throws CCAExceptionCreates a new framework instance based on the same underlying
framework implementation. This does not copy the existing
framework, nor are any of the instantiated components in the
original availble in the newly created AbstractFramework. Throws
a CCAException when the following conditions occur:
This interface is a place holder for a more complete repository interface when it becomes more fleshed out. Currently this interface just has the ability to identify the components that "preloaded" in the underlying framework implementation. There is currently no mechanism to tell the Repository where to look for components, or how they should be retrieved. This is left for future development.
array<string, 1> getLocalComponentClasses()Returns the names of components that are available to be
instantiated by gov.cca.BuilderService::createInstance() for
example.
Delivery-Date: Tue Oct 2 14:44:48 2001
>From rob Tue Oct 2 14:44:48 2001
Delivered-To: rob@localhost.ca.sandia.gov
Delivered-To: rob@glass-slipper.ca.sandia.gov
X-Authentication-Warning: z.ca.sandia.gov: majordomo set sender to owner-cca-forum@z.ca.sandia.gov using -f
Date: Tue, 2 Oct 2001 16:43:19 -0500 (EST)
From: Dennis Gannon <gannon@cs.indiana.edu>
To: <cca-forum@z.ca.sandia.gov>
Subject: builder service interface
Message-ID: <Pine.GSO.4.30.0110021613121.2254-101000@moose.cs.indiana.edu>
MIME-Version: 1.0
[1 <text/plain; US-ASCII (7bit)>]
hi,
here is a copy of the builder service we spec'd out today.
below is the text version
interface BuilderService extends Port{
ComponentID createInstance(in string className,
in string instanceName,
in TypeMap environment)
throws CCAException;
/* createInstance creates an instance of a CCA component
of the type defined by the string className. The string
classname uniquely defines the "type" of the component, i.e.
doe.cca.linearsolvers.gaussian_elminiation.
It has instance name given by the string instanceName (which may
be null). if the instance name is already known then the
function throws an exception.
*/
ComponentID getComponentID(
in string componentInstanceName)
throws CCAException;
/* returns the component ID for the named instance. throws
exception when the name matches no known instance.
*/
void destroyInstance(in ComponentID todie, float timeout )
throws CCAException;
/* eliminate this identified instance. if this operation takes
longer than "timeout" seconds, then throw and exception.
a value of 0 means to use the framework default timeout.
*/
array<string, 1> getProvidesPorts(in ComponentID cid)
throws CCAException;
array<string,1> getUsesPorts(in ComponentID cid)
throws CCAException;
/* these functions return an array of port names for a given
component instance.
*/
TypeMap getPortProperties(in ComponentID,
in string portname);
/* returns the list of public properties of a given port. */
array<ComponentID, 1> getComponents()
throws CCAException;
/* returns an array of component IDs of all components known
to the framework
*/
Array<ConnectionID, 1> getConnections(
in array<ComponentID> componentlist);
*/
ConnectionID connect(in ComponentID user,
in string usingPortName,
in ComponentID provider,
in string providingPortName,
)
throws CCAException;
/* connect creates a connection between two components. */
void disconnect(in ConnectionID id, float timeout)
throws CCAException;
/* removed connections. */
void disconnectAll(in ComponentID id,
in ComponentID id2, float timeout);
/* remove all connections between components id and id2.
if id2 is null, this removes all connections to nl
*/
}
Also included in the email Dennis's Slides *1
Delivery-Date: Wed Oct 3 13:56:37 2001
>From rob Wed Oct 3 13:56:37 2001
Delivered-To: rob@localhost.ca.sandia.gov
Delivered-To: rob@glass-slipper.ca.sandia.gov
Message-ID: <3BBB3ABA.31099466@mcs.anl.gov>
Date: Wed, 03 Oct 2001 11:20:10 -0500
From: Boyana Norris <norris@mcs.anl.gov>
X-Mailer: Mozilla 4.73 [en] (X11; I; Linux 2.2.15-4mdk i686)
X-Accept-Language: en, bg
MIME-Version: 1.0
To: rob@z.ca.sandia.gov
Subject: Re: builder service interface
Content-Transfer-Encoding: 7bit
Rob,
Here are my coppies of today's interfaces, including the
updated BuilderService.
Boyana
interface BuilderService extends Port {
// Component methods
// --------------------------------------------------------------------
/** createInstance creates an instance of a CCA component
of the type defined by the string className. The string
classname uniquely defines the "type" of the component, i.e.
doe.cca.linearsolvers.gaussian_elminiation.
It has instance name given by the string requestedInstanceName (which may
be null). if the instance name is already known then the
function throws an exception.
*/
ComponentID createInstance(in string className, in string requestedInstanceName, in TypeMap environment) throws CCAException;
array<ComponentID,1> getComponentIDs() throws CCAException;
/** Returns the component ID for the named instance. throws
exception when the name matches no known instance.
*/
ComponentID getComponentID( in string componentInstanceName ) throws CCAException;
/** Get the properties of the component that the framework
wishes to expose.
*/
TypeMap getComponentProperties(in ComponentID cid) throws CCAException;
/** Returns a ComponentID from the string returned from
ComponentID::getSerialization().
*/
ComponentID getDeserialization(in string s) throws CCAException;
/** Eliminate this identified instance. if this operation takes
longer than "timeout" seconds, then throw and exception.
a value of 0 means to use the framework default timeout.
*/
void destroyInstance(in ComponentID todie, float timeout ) throws CCAException;
void destroyNamedInstance(in string ComponentName, float timeout) throws CCAException;
// Port methods
// --------------------------------------------------------------------
/** Returns an array of provides port names for a given component instance.
*/
array<string,1> getProvidesPorts(in ComponentID cid) throws CCAException;
/** Returns an array of uses port names for a given component instance.
*/
array<string,1> getUsesPorts(in ComponentID cid) throws CCAException;
/** Returns the list of public properties of a given port.
*/
TypeMap getPortProperties(in ComponentID cid, in string portName) throws CCAException;
// Connection methods
// --------------------------------------------------------------------
/** Create a connection between two components
*/
ConnectionID connect(in ComponentID user,
in string userPortName,
in ComponentID provider,
in string providingPortName) throws CCAException;
array<ConnectionID,1> getConnectionIDs() throws CCAException;
getConnectionProperties(in ConnectionID id) throws CCAException;
/** Remove a connection; throw an exception if it takes longer than timeout seconds
Specify timeout=0 to use the framework default.
*/
void disconnect(in ConnectionID id, float timeout) throws CCAException;
/** Remove all connections; throw an exception if it takes longer than timeout seconds
Specify timeout=0 to use the framework default.
*/
void disconnectAll(in ComponentID cid1, in ComponentID cid2, float timeout) throws CCAException;
}
interface ComponentID {
/** Returns the instance name provided in
BuilderService::createInstance().
*/
string getInstanceName() throws CCAException;
/** Returns a serialization of the ComponentID.
(framework-specific)
*/
string getSerialization() throws CCAException;
}
interface ConnectionID {
ComponentID getProvider() throws CCAException;
ComponentID getUser() throws CCAException;
string getProvidesPortName() throws CCAException;
string getUsesPortName() throws CCAException;
}
interface Framework {
/** Return empty TypeMap instance
*/
TypeMap createTypeMap();
Services getServices(in string selfInstanceName,
in string selfClassName,
in TypeMap selfProperties) throws CCAException;
void releaseServices(in Services svc) throws CCAException;
void shutdownFramework() throws CCAException;
/** Creates a new framework instance based on the same
underlying framework implementation. This way, a main()
building several containers (possible nesting them) can
pick the implementation class of the framework once and then
everywhere else clone new instances without hard-coding the framework type.
The clone is shallow, i.e. it does not create copies of any
components within the original framework.
*/
Framework cloneEmptyFramework() throws CCAException;
}
*1 Note:
that BS her refers to BuilderService and not any commentary on
Dennis's view grafs.