* Subtle interpretation: If the Component is not listening for * Disconnect events, then the framework has no clean way to * break the connection until after the component calls releasePort. *
*The framework may go through some machinations to obtain * the port, possibly involving an interactive user or network * queries, before giving up and throwing an exception. *
* * @param portName The previously registered or provide port which * the component now wants to use. * @exception CCAException with the following types: NotConnected, PortNotDefined, * NetworkError, OutOfMemory. */ Port getPort(in string portName) throws CCAException; /** * Get a previously registered Port (defined by * either addProvide or registerUses) and return that * Port if it is available immediately (already connected * without further connection machinations). * There is an contract that the * port will remain valid per the description of getPort. * @return The named port, if it exists and is connected or self-provided, * or NULL if it is registered and is not yet connected. Does not * return if the Port is neither registered nor provided, but rather * throws an exception. * @param portName registered or provided port that * the component now wants to use. * @exception CCAException with the following types: PortNotDefined, OutOfMemory. */ Port getPortNonblocking(in string portName) throws CCAException; /** * Notifies the framework that this component is finished * using the previously fetched Port that is named. * The releasePort() method calls should be paired with * getPort() method calls; however, an extra call to releasePort() * for the same name may (is not required to) generate an exception. * Calls to release ports which are not defined or have never be fetched * with one of the getPort functions generate exceptions. * @param portName The name of a port. * @exception CCAException with the following types: PortNotDefined, PortNotInUse. */ void releasePort(in string portName) throws CCAException; /** * Creates a TypeMap, potentially to be used in subsequent * calls to describe a Port. Initially, this map is empty. */ TypeMap createTypeMap() throws CCAException; /** * Register a request for a Port that will be retrieved subsequently * with a call to getPort(). * @param portName A string uniquely describing this port. This string * must be unique for this component, over both uses and provides ports. * @param type A string desribing the type of this port. * @param properties A TypeMap describing optional properties * associated with this port. This can be a null pointer, which * indicates an empty list of properties. Properties may be * obtained from createTypeMap or any other source. The properties * be copied into the framework, and subsequent changes to the * properties object will have no effect on the properties * associated with this port. * In these properties, all frameworks recognize at least the * following keys and values in implementing registerUsesPort: ** key: standard values (in string form) default * "MAX_CONNECTIONS" any nonnegative integer, "unlimited". 1 * "MIN_CONNECTIONS" any integer > 0. 0 * "ABLE_TO_PROXY" "true", "false" "false" ** The component is not expected to work if the framework * has not satisfied the connection requirements. * The framework is allowed to return an error if it * is incapable of meeting the connection requirements, * e.g. it does not implement multiple uses ports. * The caller of registerUsesPort is not obligated to define * these properties. If left undefined, the default listed above is * assumed. * @exception CCAException with the following types: PortAlreadyDefined, OutOfMemory. */ void registerUsesPort(in string portName, in string type, in TypeMap properties ) throws CCAException ; /** * Notify the framework that a Port, previously registered by this * component but currently not in use, is no longer desired. * Unregistering a port that is currently * in use (i.e. an unreleased getPort() being outstanding) * is an error. * @param portName The name of a registered Port. * @exception CCAException with the following types: UsesPortNotReleased, PortNotDefined. */ void unregisterUsesPort(in string portName) throws CCAException ; /** * Exposes a Port from this component to the framework. * This Port is now available for the framework to connect * to other components. * @param inPort An abstract interface (tagged with CCA-ness * by inheriting from gov.cca.Port) the framework will * make available to other components. * * @param portName string uniquely describing this port. This string * must be unique for this component, over both uses and provides ports. * * @param type string describing the type (class) of this port. * * @param properties A TypeMap describing optional properties * associated with this port. This can be a null pointer, which * indicates an empty list of properties. Properties may be * obtained from createTypeMap or any other source. The properties * be copied into the framework, and subsequent changes to the * properties object will have no effect on the properties * associated with this port. * In these properties, all frameworks recognize at least the * following keys and values in implementing registerUsesPort: *
* key: standard values (in string form) default * "MAX_CONNECTIONS" any nonnegative integer, "unlimited". 1 * "MIN_CONNECTIONS" any integer > 0. 0 * "ABLE_TO_PROXY" "true", "false" "false" ** The component is not expected to work if the framework * has not satisfied the connection requirements. * The framework is allowed to return an error if it * is incapable of meeting the connection requirements, * e.g. it does not implement multiple uses ports. * The caller of addProvidesPort is not obligated to define * these properties. If left undefined, the default listed above is * assumed. * @exception CCAException with the following types: PortAlreadyDefined, OutOfMemory. */ void addProvidesPort(in Port inPort, in string portName, in string type, in TypeMap properties ) throws CCAException ; /** Returns the complete list of the properties for a Port. This includes the properties defined when the port was registered (these properties can be modified by the framework), two special properties "cca.portName" and "cca.portType", and any other properties that the framework wishes to disclose to the component. The framework may also choose to provide only the subset of input properties (i.e. from addProvidesPort/registerUsesPort) that it will honor. */ TypeMap getPortProperties(in string name) ; /** Notifies the framework that a previously exposed Port is no longer * available for use. The Port being removed must exist * until this call returns, or a CCAException may occur. * @param portName The name of a provided Port. * @exception PortNotDefined. In general, the framework will not dictate * when the component chooses to stop offering services. */ void removeProvidesPort(in string portName) throws CCAException ; /** * Get a reference to the component to which this * Services object belongs. */ ComponentID getComponentID(); /** Obtain a callback for component destruction. * @param callBack an object that implements the ComponentRelease * interface that will be called when the component is to be destroyed. * * Register a callback to be executed when the component is going * to be destroyed. During this callback, the Services object passed * through setServices will still be valid, but after all such * callbacks are made for a specific component, subsequent usage * of the Services object is not allowed/is undefined. */ void registerForRelease(in ComponentRelease callBack) throws CCAException; } /** * All components must implement this interface. */ interface Component { /** Starts up a component presence in the calling framework. * @param services the component instance's handle on the framework world. * Contracts concerning Svc and setServices: * * The component interaction with the CCA framework * and Ports begins on the call to setServices by the framework. * * This function is called exactly once for each instance created * by the framework. * * The argument Svc will never be nil/null. * * Those uses ports which are automatically connected by the framework * (so-called service-ports) may be obtained via getPort during * setServices. */ void setServices(in Services services) throws CCAException; } /** An interface so the framework can inform the component when the component is about to be destroyed. Components managing memory, files, or other global resources should usually implement this interface and register it via Services.registerForRelease. */ interface ComponentRelease { /** * Shuts down a component presence in the calling framework. * @param services the component instance's handle on the framework world. * Contracts concerning Svc and setServices: * * This function is called exactly once for each callback registered * through Services. * * The argument Svc will never be nil/null. * The argument Svc will always be the same as that received in * setServices. * * During this call the component should release any interfaces * acquired by getPort(). * * During this call the component should reset to nil any stored * reference to Svc. * * After this call, the component instance will be removed from the * framework. If the component instance was created by the * framework, it will be destroyed, not recycled, The behavior of * any port references obtained from this component instance and * stored elsewhere becomes undefined. * * Notes for the component implementor: * 1) The component writer may perform blocking activities * within releaseServices, such as waiting for remote computations * to shutdown. * 2) It is good practice during releaseServices for the component * writer to remove or unregister all the ports it defined. */ void releaseServices(in Services services) throws CCAException; } /** * An opaque reference to a Component. */ interface ComponentID { /** * Returns the instance name provided in *
BuilderService.createInstance()
* or in
* AbstractFramework.getServices().
* @throws CCAException if ComponentID is invalid
*/
string getInstanceName() throws CCAException ;
/**
* Returns a framework specific serialization of the ComponentID.
* @throws CCAException if ComponentID is
* invalid.
*/
string getSerialization() throws CCAException ;
}
/** The primitive data types (and arrays of same) supported by CCA
TypeMaps and Babel. */
enum Type {
NoType, Int, Long, Float, Double, Fcomplex, Dcomplex, String, Bool,
IntArray, LongArray, FloatArray, DoubleArray, FcomplexArray,
DcomplexArray, StringArray, BoolArray
}
/** Detailed exception describing a type mismatch in getting
or setting a value in a TypeMap. */
interface TypeMismatchException extends CCAException {
/** @return the enumerated value Type sought */
Type getRequestedType();
/** @return the enumerated value Type sought */
Type getActualType();
}
/**
* A CCA map. Maps a string key to a particular value. Types are
* strictly enforced. For example, values places into the map
* using putInt can be retrieved only using getInt. Calls to
* getLong, getString, getIntArray and other get methods will
* fail (i.e. return the default value).
*/
interface TypeMap {
/** Create an exact copy of this Map */
TypeMap cloneTypeMap();
/** Create a new Map with no key/value associations. */
TypeMap cloneEmpty();
/*
* Get the scalar value associated with a given key. If the key
* was not found, return the default value.
*/
int getInt(in string key, in int dflt) throws TypeMismatchException;
long getLong(in string key, in long dflt) throws TypeMismatchException;
float getFloat(in string key, in float dflt) throws TypeMismatchException;
double getDouble(in string key, in double dflt) throws TypeMismatchException;
fcomplex getFcomplex(in string key, in fcomplex dflt) throws TypeMismatchException;
dcomplex getDcomplex(in string key, in dcomplex dflt) throws TypeMismatchException;
string getString(in string key, in string dflt) throws TypeMismatchException;
bool getBool(in string key, in bool dflt) throws TypeMismatchException;
/*
* Get an array value associated with a given key. If the key
* was not found, return the dflt value.
*/
arrayExample
** Here it is assumed that an instance of AbstractFramework * is created in the main() from some hypothetical implementation. * The idea is to allow a complete swap of framework choice by * changing out the specified implementation class of a framework. *
* *
* // java
* main() {
* cca.reference.Framework fwkimpl = new cca.reference.Framework();
* // change fwkimpl above to use different cca implementations when
* // AbstractFramework becomes part of the standard.
* gov.cca.AbstractFramework fwk = (gov.cca.AbstractFramework)fwkimpl;
* gov.cca.Services svc =
* fwk.getServices("instance0","AppDriver",null);
* // From here on, access all services, components, etc
* // through svc.
* ...
* // when done
* fwk.releaseServices(svc);
* fwk.shutdownFramework();
* }
*
* // c++
* int functionName() {
* ::gov::sandia::ccafe::Framework fwkimpl;
* ::gov::cca::AbstractFrameworkPtr fwk;
*
* fwk = fwkimpl.getStandardFramework();
* ::gov::cca::Services_Interface * svc = 0;
* svc = fwk->getServices("instance0","AppDriver",0);
* // From here on, access all services, components, etc
* // through svc.
* ...
* // when done
* fwk->releaseServices(svc);
* svc = 0;
* fwk->shutdownFramework();
*
* // at scope exit, all memory is automatically cleaned up.
* }
* getServices(). The "normal" method of
* creating typemaps is found in the Services interface. It
* is duplicated here to break the "chicken and egg" problem.
*/
TypeMap createTypeMap() throws CCAException;
/**
* Retrieve 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.
* This method may be called any number of times
* with different arguments, creating a new component image
* each time.
* The only proper method to destroy a Services obtained
* from this interface is to pass it to releaseServices.
*
* @param selfInstanceName the Component instance name,
* as it will appear in the framework.
*
* @param selfClassName the Component type of the
* calling program, as it will appear in the framework.
*
* @param selfProperties (which can be null) the properties
* of the component image to appear.
*
* @throws CCAException in the event that selfInstanceName
* is already in use by another component.
*
* @return A Services object that pertains to the
* image of the this component. This is identical
* to the object passed into Component.setServices()
* when a component is created.
*/
Services getServices(in string selfInstanceName, in string selfClassName,
in TypeMap selfProperties) throws CCAException ;
/**
* Inform framework that the Services handle is no longer needed by the
* caller and that the reference to its component image is to be
* deleted from the context of the underlying framework. This invalidates
* any ComponentID's or ConnectionID's associated
* with the given Services' component image.
*
* @param services The result of getServices earlier obtained.
*
* @throws CCAException if the Services
* handle has already been released or is otherwise rendered invalid
* or was not obtained from getServices().
*/
void releaseServices(in Services services) throws CCAException ;
/**
* Tell the framework it is no longer needed and to clean up after itself.
* @throws CCAException if the framework has already been shutdown.
*/
void shutdownFramework() throws CCAException;
/**
* Creates a new framework instance based on the same underlying
* framework implementation. This does not copy the existing
* framework, nor are any of the user-instantiated components in
* the original framework available in the newly created
* AbstractFramework.
*
* @throws CCAException when one of the following conditions occur:
*
* (1)the AbstractFramework previously had shutdownFramework() called on it, or
* (2)the underlying framework implementation does not permit creation
* of another instance.
*/
AbstractFramework createEmptyFramework() throws CCAException;
} // end interface AbstractFramework
/**
* This interface describes a CCA connection between components.
* A connection is made at the users direction
* 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 Ports are referred to
* by their string instance names.
*/
interface ConnectionID {
/**
* Get the providing component (callee) ID.
* @return ComponentID of the component that has
* provided the Port for this connection.
* @throws CCAException if the underlying connection
* is no longer valid.
*/
ComponentID getProvider() throws CCAException ;
/**
* Get the using component (caller) ID.
* @return ComponentID of the component that is using the provided Port.
* @throws CCAException if the underlying connection is no longer valid.
*/
ComponentID getUser() throws CCAException ;
/**
* Get the port name in the providing component of this connection.
* @return the instance name of the provided Port.
* @throws CCAException if the underlying connection is no longer valid.
*/
string getProviderPortName() throws CCAException ;
/**
* Get the port name in the using component of this connection.
* Return the instance name of the Port registered for use in
* this connection.
* @throws CCAException if the underlying connection is no longer valid.
*/
string getUserPortName() throws CCAException ;
}
/**
* An opaque reference to a Component Class.
* (This interface is expected to grow substantially.)
*/
interface ComponentClassDescription {
/**
* Returns the class name provided in
* BuilderService.createInstance()
* or in
* AbstractFramework.getServices().
*
* Throws CCAException if ComponentClassDescription is invalid.
*/
string getComponentClassName() throws CCAException ;
} // end interface ComponentClassDescription
/**
* some standard (required) CCA ports.
*/
package ports {
/**
* Go, component, go!
*/
interface GoPort extends Port {
/**
* Execute some encapsulated functionality on the component.
* Return 0 if ok, -1 if internal error but component may be
* used further, and -2 if error so severe that component cannot
* be further used safely.
*/
int go();
}
/**
* The minimum kinds of events needed. List to be extended
* in the future. Clearly, SMP architectures and threads may
* violate the simple assumptions.
*/
enum EventType {
Error = -1, // Someone got a bogus event object somehow.
ALL = 0, // Component wants to receive all event notices.
// ALL itself never received.
ConnectPending = 1, // A connection is about to be attempted.
Connected = 2, // A connection has been made.
DisconnectPending = 3, // A disconnection is about to be attempted.
Disconnected = 4, // A disconnection has been made.
}
/**
* Event created when two components are connected.
*/
interface ConnectionEvent {
/**
*
Returns the integer from those enumerated that describes the event.
* ** The semantics are noted before * each member of the enum/static constant. We can add in different * types of connect/disconnect as multiports and * explicit local/global/sync/async semantics are agreed to in the future. * At present we assume that: *
* Clearly some of the assumptions above may not suit a component
* instance in which multiple execution threads act on a
* single instance of the cca.Services object (SMP). The Services
* specification is ambiguous as to whether such a component is even
* allowed.
*
* When this is clarified, additional members of the enum may arise,
* in which case the assumptions here apply only to
* ConnectPending, Connected, DisconnectPending,
* Disconnected types.
*/
EventType getEventType();
/**
* Get Properties of the affected Port.
* Among the standard properties are the name and type info.
* The keys are cca.portName, cca.portType.
*/
cca.TypeMap getPortInfo();
}
/**
* This is the interface that a component must provide in order to
* be notified of ConnectEvents.
*/
interface ConnectionEventListener {
/**
* Called on all listeners when a connection is made or broken.
*/
void connectionActivity(in ConnectionEvent ce);
}
/**
* Connection event service.
*/
interface ConnectionEventService extends cca.Port {
/**
* Sign up to be told about connection activity.
* connectionEventType must be one of the integer
* values defined iN ConnectionEvent.
*/
void addConnectionEventListener(in EventType et,
in ConnectionEventListener cel);
/**
* Ignore future ConnectionEvents of the given type.
* connectionEventType must be one of the integer values
* defined in ConnectionEvent.
*/
void removeConnectionEventListener(in EventType et,
in ConnectionEventListener cel);
}
/**
* 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.
*
Each of the fundamental component architecture pieces * (instances of Component, Port, and Connection) may have * an associated TypeMap of properties managed by the framework. * The standardized keys in the properties of a Port are documented * in Services.getPortProperties(). * The standardized keys in the properties of a Component and Connection * are documented below. *
*For connection, thus far: *
* Key value meaning * cca.isInUse boolean true if there have been more successful * getPort than releasePort calls for the * connection at the the time * properties were fetched. ** *
For component, thus far: *
* Key value meaning * cca.className string component type ** */ interface BuilderService extends cca.Port { /** * 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, e.g. * doe.cca.Library.GaussianElmination. * It has an instance name given by the string instanceName. * The instanceName may be empty (zero length) in which case * the instanceName will be assigned to the component automatically. * @throws CCAException If the Component className is unknown, or if the * instanceName has already been used, a CCAException is thrown. * @return A ComponentID corresponding to the created component. Destroying * the returned ID does not destroy the component; * see destroyInstance instead. */ cca.ComponentID createInstance(in string instanceName, in string className, in cca.TypeMap properties) throws cca.CCAException ; /** * Get component list. * @return a ComponentID for each component currently created. */ array