gov.cca.Services Interface Reference
The one interface all frameworks must implement.
More...
List of all members.
|
Public Member Functions |
Port | getPort (in string portName) throws CCAException |
| Fetch a previously registered Port (defined by either addProvidePort or (more typically) registerUsesPort).
|
Port | getPortNonblocking (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).
|
void | releasePort (in string portName) throws CCAException |
| Notifies the framework that this component is finished using the previously fetched Port that is named.
|
TypeMap | createTypeMap () throws CCAException |
| Creates a TypeMap, potentially to be used in subsequent calls to describe a Port.
|
void | registerUsesPort (in string portName, in string type, in TypeMap properties) throws CCAException |
| Register a request for a Port that will be retrieved subsequently with a call to getPort().
|
void | unregisterUsesPort (in string portName) throws CCAException |
| Notify the framework that a Port, previously registered by this component but currently not in use, is no longer desired.
|
void | addProvidesPort (in Port inPort, in string portName, in string type, in TypeMap properties) throws CCAException |
| Exposes a Port from this component to the framework.
|
TypeMap | getPortProperties (in string name) |
| Returns the complete list of the properties for a Port.
|
void | removeProvidesPort (in string portName) throws CCAException |
| Notifies the framework that a previously exposed Port is no longer available for use.
|
ComponentID | getComponentID () |
| Get a reference to the component to which this Services object belongs.
|
void | registerForRelease (in ComponentRelease callBack) throws CCAException |
| Obtain a callback for component destruction.
|
Detailed Description
The one interface all frameworks must implement.
A unique instance of this is given to each component.
Member Function Documentation
void gov.cca.Services.addProvidesPort |
( |
in Port |
inPort, |
|
|
in string |
portName, |
|
|
in string |
type, |
|
|
in TypeMap |
properties | |
|
) |
| | throws CCAException |
Exposes a Port from this component to the framework.
This Port is now available for the framework to connect to other components.
- Parameters:
-
| inPort | An abstract interface (tagged with CCA-ness by inheriting from gov.cca.Port) the framework will make available to other components. |
| portName | string uniquely describing this port. This string must be unique for this component, over both uses and provides ports. |
| type | string describing the type (class) of this port. |
| 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. |
- Exceptions:
-
| CCAException | with the following types: PortAlreadyDefined, OutOfMemory. |
Creates a TypeMap, potentially to be used in subsequent calls to describe a Port.
Initially, this map is empty.
Fetch a previously registered Port (defined by either addProvidePort or (more typically) registerUsesPort).
- Returns:
- Will return the Port (possibly waiting forever while attempting to acquire it) or throw an exception. Does not return NULL, even in the case where no connection has been made. If a Port is returned, there is then a contract that the port will remain valid for use by the caller until the port is released via releasePort(), or a Disconnect Event is successfully dispatched to the caller, or a runtime exception (such as network failure) occurs during invocation of some function in the Port.
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.
- Parameters:
-
| portName | The previously registered or provide port which the component now wants to use. |
- Exceptions:
-
| CCAException | with the following types: NotConnected, PortNotDefined, NetworkError, OutOfMemory. |
Port gov.cca.Services.getPortNonblocking |
( |
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.
- Returns:
- 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.
- Parameters:
-
| portName | registered or provided port that the component now wants to use. |
- Exceptions:
-
| CCAException | with the following types: PortNotDefined, OutOfMemory. |
TypeMap gov.cca.Services.getPortProperties |
( |
in string |
name |
) |
|
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.
Obtain a callback for component destruction.
- Parameters:
-
| 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 gov.cca.Services.registerUsesPort |
( |
in string |
portName, |
|
|
in string |
type, |
|
|
in TypeMap |
properties | |
|
) |
| | throws CCAException |
Register a request for a Port that will be retrieved subsequently with a call to getPort().
- Parameters:
-
| portName | A string uniquely describing this port. This string must be unique for this component, over both uses and provides ports. |
| type | A string desribing the type of this port. |
| 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. |
- Exceptions:
-
| CCAException | with the following types: PortAlreadyDefined, OutOfMemory. |
void gov.cca.Services.releasePort |
( |
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.
- Parameters:
-
| portName | The name of a port. |
- Exceptions:
-
| CCAException | with the following types: PortNotDefined, PortNotInUse. |
void gov.cca.Services.removeProvidesPort |
( |
in string |
portName |
) |
throws CCAException |
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.
- Parameters:
-
| portName | The name of a provided Port. |
- Exceptions:
-
| PortNotDefined. | In general, the framework will not dictate when the component chooses to stop offering services. |
void gov.cca.Services.unregisterUsesPort |
( |
in string |
portName |
) |
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.
- Parameters:
-
| portName | The name of a registered Port. |
- Exceptions:
-
| CCAException | with the following types: UsesPortNotReleased, PortNotDefined. |
The documentation for this interface was generated from the following file: