gov.cca.ports
Interface KeyValuePort

All Superinterfaces:
Port

public interface KeyValuePort
extends Port

KeyValuePort for use decorating components with strings external to the implementation of the component. The keys may not contain whitespace or =. The values may be anything in a String. Alternative, misleading names for this class would be

   EnvironmentPort (which has too many global connotations)
   RegistryPort (which has way too many global connotations)
   PropertiesPort (which will be confused with port properties and java Properties...).
   ParameterPort (which is already taken in the CCAFFEINE framework.).
 
This class is deliberately simpler than java Properties, for compatibility with basic c++ interfaces. In a reasonable framework, each component will just be automatically decorated with one of these if that framework exposes the component to external agents. The following code fragment illustrates the use of the KeyValuePort by a framework Services implementation to decorate every component with a properties for the frameworks use.

     String[] dummy = null;
     try {
       addProvidesPort(kvp,createPortInfo("cProps","gov.cca.ComponentProperties",dummy));
     } catch (Exception e) { // cannot fail, due to other framework design features }
 
The following code fragment illustrates the use of the port as a service by a component that wants to know/modify what the framework says about it.
   setServices(Services s) {
     String[] dummy = null;
     try {
       s.registerUsesPort(kvp,createPortInfo("sProps","gov.cca.ComponentPropertiesService",dummy));
     } catch (Exception e) { // cannot fail, if we adopt it as a well known service. }
   KeyValuePort kvp = (KeyValuePort)getPort("sProps");
   kvp.setValue("gov.babel.guiApplet.URL",
                "http://z.ca.sandia.gov/cgi-bin/babel.asp?component=gov.sandia.viz");
   s.releasePort("sProps");
   s.unregisterUsesPort("sProps");
 


Method Summary
 java.util.Enumeration getKeys()
          Return enumeration of all known keys.
 java.lang.String getValue(java.lang.String key)
          Return the value of the requested key.
 java.lang.String remove(java.lang.String key)
          Delete a key and associated value.
 int setValue(java.lang.String key, java.lang.String value)
          Store the value for the given key, possibly replacing previous.
 

Method Detail

getValue

java.lang.String getValue(java.lang.String key)
Return the value of the requested key. If key unknown, returns null.


setValue

int setValue(java.lang.String key,
             java.lang.String value)
Store the value for the given key, possibly replacing previous. Keys cannot contain the whitespace or '='. Returns nonzero on bogus input or other error.


remove

java.lang.String remove(java.lang.String key)
Delete a key and associated value. The deleted value is returned.


getKeys

java.util.Enumeration getKeys()
Return enumeration of all known keys. May be empty.