The Creation Service is a framework specific component (so called a pseudo component) that allows one component to instantiate other components. This service completely encapsulates the component instantiation mechanism thus freeing the component developer from low-level, framework-specific details of instantiation related issues.

The service exports one provides port (called CreationService) with two functions. The createInstance function takes a url describing the component to be created, the instantiation mechanism to be used, the host on which the component is to be instantiated, and returns a ComponentID that act as a reference for the created component. The function also takes an environment object as a second parameter that can be used to specify additional information to the creation service. This information may include full pathname of the component executable, instantiation mechanism specific information, other information that needs to be passed on to the instantiated component, such as command line parameters, and process environment variables like LD_LIBRARY_PATH, PATH, stdin, stdout and stderr.

A component can be created in the same address space environment of the creating component or it may be instantiated in a different address space on a different host.

The deleteInstance function destroys the component specified by a given ComponentID.

The semantics of method calls is based on the Corba specifications:

1. If the call does not throw an exception, then the call semantics is exactly once. This means that the operation was performed exactly once and that it succeeded.
2. If there was an exception, then the call semantics is at most once. This means that the operation may have succeeded or not, but it was not done more than once.

• stringSeq, PortInfoSeq

  typedef sequence stringSeq;
  	      typedef sequence PortInfoSeq;
  		// Note: If we switch to SIDL to specify interfaces, then we could use SIDL
  		//       arrays instead of Corba IDL sequences
  	  

• EnvObj
  

  valuetype EnvObj {
    public string get (in string name);
    public void put (in string name, in string val);
    public stringSeq getAllNames ();
  };
  	  

• ComponentID
  

  valuetype ComponentID {
    public PortInfoSeq getProvidesPorts();
    public PortInfoSeq getUsesPorts();
  };
  	  

• CreationService
  

  // Provides Ports
  interface CreationService: CCAPort {
  
    public ComponentID createInstance(in string url, inout EnvObj env)
           raises (InstantiateException);
  
    public void deleteInstance(in ComponentID id)
           raises (InstantiateException);
  };
  	  

• EnvObj
  

  class EnvObj {
  public:
    virtual char* get (char* name) = 0;
    virtual void put (char* name, char* val) = 0;
    virtual void getAllNames (char ** names, int &len) = 0;
  };
  	  

• ComponentID
  

  class ComponentID {
  public:
    virtual PortInfo** getProvidesPorts(int &len) = 0;
    virtual PortInfo** getUsesPorts(int &len) = 0;
  };
  	  

• CreationService
  

  class CreationService: public Port {
  public:
    virtual ComponentID* createInstance(char* url, EnvObj* env)
    throw (InstantiateException) = 0;
  
    virtual void deleteInstance(ComponentID* id)
    throw (InstantiateException) = 0;
  };
  	  

• EnvObj
  

  interface EnvObj {
    public String get (String name);
    public void put (String name, String val);
    public String [] getAllNames ();
  }
  	  

• ComponentID
  

  interface ComponentID {
    public PortInfo[] getProvidesPorts();
    public PortInfo[] getUsesPorts();
  }
  	  

• Creation Service
  

  interface CreationService: CCAPort {
  
    public ComponentID createInstance(String url, EnvObj env)
    throws InstantiateException;
  
    public void deleteInstance(ComponentID id)
    throws InstantiateException;
  }
  	  

• EnvObj
  
  

  • string get (in string name);
    	      

    • Parameters
      • name: specifies the name string to be looked up in the environment.
    • Semantics
      • Returns the value associated with a given name.
      • If name does not exist, then a null value is returned. In the C++ binding, a null pointer is returned, while is Java a null reference is returned.
      • In the C++ binding, the returned string is owned by the EnvObj object and not to be deleted by the user.

  • void put (in string name, in string val);
    	  

    • Parameters
      • name: specifies the name string to be added in the environment. The name acts as a key for accessing the environment object.
      • val: specifies the value to be associated with the give name.
    • Semantics
      • Adds the given name - value pair to the environment object.
      • In the C++ binding, the put function makes a copy of the name and the value before storing them internally. Thus, the caller can destroy the name or value immediately after returning from the call.

  • stringSeq getAllNames ();
    	  

    • Parameters
      This call is mapped differently for Java and for C++. This is because in Java, arrays are objects and have a length field associated with them that can be used to find their length. In C++, the array length needs to be specified separately and so this function specifies the array length through a parameter. Also, in the C++ binding, the array is passed in as a parameter to the call and is filled up by the function before returning.
      So, for C++ binding only:
      • names: An array of strings used as an inout parameter by the function. This is filled up by the function with all the names (i.e. keys) in the EnvObj.
      • length: The length is also an inout parameter. As an in parameter, it specifies the length of the array passed in, and as an out parameter, it specifies the number of names actually filled in by the function.
    • Semantics
      • Gets all the names stored in the environment object.
      • In the C++ binding, the names array is an array of "char *" and the caller is supposed to pass a large enough array to hold all the names. The function sets the "char *" elements of the array with the names in the EnvObj. Thus, the caller owns the array of "char *"s that was sent in; while the actual strings pointed to be the individual elements of the array are still owned by the EnvObj, and thus should not be destroyed by the caller. (This semantics is really quite awkward, but in the absence of smart reference counting, this is what we get :( )
• CreationService
  
  

  • ComponentID createInstance(in String url, inout EnvObj env) 
                raises (InstantiateException); 
    	  

    • Parameters
    • url: instantiation-mechanism:/target-host/component-full-name
      where:
      1. instantiation-mechanism: This specifies the instantiation mechanism to be used while instantiating the component. Currently defined mechanisms are:
         1. gram: instantiation using Globus GRAM (Globus Resource Allocation Manager).
         2. rsh: using Unix rsh
         3. ssh: using Unix ssh
         4. local: starting the component as a separate process on the local machine.
         5. in-process: starting the component inside the same process as the caller.
         
      2. target-host: machine on which to instantiate the component. It will be blank in case of the "local" and the "in-process" instantiation mechanisms. For any other instantiation mechanism, if host is blank, the component will be instantiated on the same host as the caller.
      3. component-full-name: full name of the component to be instantiated.

      url examples:
      gram:/rainier.extreme.indiana.edu/components/cat/cca/lsa/NewSystem
      local://components/cat/cca/lsa/SpLib
      in-process://components/cat/cca/LoadChecker
      

    • env: The env object contains a set of name-value string pairs (Similar to Globus GRAM Resource Specification Language). It can be used for the following purposes:
      1. To provide creation mechanism independent additional information about the component to be instantiated. This will typically include:
         • POSIX environment variables to be sent to the component:
           stdin, stdout, stderr, LD_LIBRARY_PATH, PATH, WD (working directory), TMPDIR, SHELL etc.
         • Information specifying locations of standard framework services:
           When a component starts up, it can be provided with a set of environment parameters that will specify the network locations of the standard framework services such as the registry and the information directory service (IDS). Currently defined environment variables are: REGISTRY_HOST, REGISTRY_PORT, IDS_HOST, IDS_PORT.
      2. To provide creation mechanism specific additional information. This information could further be categorized as:
         • Variables defined by the underlying creation mechanism: For example, if gram is the creation mechanism, these could be used to provide resource requests for the creation, such as amount of memory desired or the number of processors required (for a multi-processor machine). The names of these parameters will be as defined by the specific creation mechanism. For example, Globus GRAM defines these parameters through the RSL spec. Similar variables are defined if MPI is used for creating components.
         • Other miscellaneous information:
           1. executable: This specifies the full path name of the executable on the target machine, assuming that for a single component, different creation mechanisms may require different executables. If the same executable is always usable across different creation mechanisms, then this variable could be categorized as creation mechanism independent information.
           2. user authentication object: information used to authenticate the user making this call.
      3. To provide application level command line parameters to the component executable.
      4. This variable is used as an inout parameter, that means it will also return some information if the call succeeds. If instantiation succeeds, the function will add the component's creation time into the environment object under the name creationTime. So, if the call succeeds, the caller can query the environment object to get the component's creation time. The same environment object may be used for the registry service's bind call. The createInstance function will also add the creationMechanism and the target host for the created component in the environment object. They can be used the same way as the creationTime.
    • Semantics
    • The createInstance function implementation will use the given instantiation mechanism to instantiate a component instance on the specified target machine and return a ComponentID representing the component. If no exception is thrown following the function call, the caller can use the ComponentID to make invocations on the created component. If successful, this call publishes the ComponentCreationEvent. The value of the returned ComponentID is undefined if an exception is thrown.
    • If the instantiation fails for whatever reason, an InstantiateException is thrown.
    • In the C++ binding, a pointer to ComponentID is returned. The memory for the ComponentID is allocated on heap and when the call returns successfully, the ownership is given to the caller. Thus, it's the caller's responsibility to deallocate the ComponentID pointer once it's done using it. Deleting the ComponentID pointer will not destroy the component identified by the ComponentID. In order to destroy the component, the deleteInstance function must be called.
    
    
    

  • void deleteInstance(in ComponentID id) raises (InstantiateException); 
          

    • Parameters
      • ComponentID: The ComponentID of the component to be deleted. It's the caller's responsibility to provide a valid ComponentID. The effect of providing an invalid ComponentID is undefined.
    • Semantics
      • The function uses whatever mechanism appropriate to destroy the component identified by the ComponentID. Whether the call succeeds or not, the ComponentID should not be used to make any further invocations on the component. If successful, this call publishes a ComponentDestructionEvent.
      • If unsuccessful, this function throws an InstantiateException.
      • When this function is called, the CCA Framework will call "setServices()" with a null argument on the target component. This is the standard way in which a component is notified that it should terminate execution.

• Java Example: This example shows Java code belonging to a CCA component that creates an instance of another component using the Globus "gram" instantiation mechanism and later destroys it. It shows how to create the environment object from scratch.
  

  // Use the component's services object to get a uses port connected 
  // to the creation service.
  CreationService creationPort = 
                  (CreationService) services.getPort("CreationService");
  
  // make the component creation url: this example uses
  // 1. Globus "gram" as the creation mechanism
  // 2. "bread.extreme.indiana.edu" as the target machine
  // 3. The component to be created is: "/components/cat/cca/NewSystem". This is
  //    the scoped name of the component as maintained by the information
  //    directory service (IDS)
  String url = "gram:/bread.extreme.indiana.edu/components/cat/cca/NewSystem";
  
  // Create an environment object to be passed to the createInstance call
  EnvObj env = new EnvObj();
  
  // where to find the executable
  env.put ("executable", "/u/ccat/components/bin/NewSystem.exe");
  
  // Specify environment variables for the executable
  env.put ("stdin", "/u/ccat/components/src/NewSystem/input_file");
  env.put ("stdout", "/dev/null");
  env.put ("stderr", "/u/ccat/components/src/NewSystem/error_file");
  
  // create component
  try {
    ComponentID cid = creationPort.createInstance(url, env);
  } catch (InstantiateException excep) {
    System.out.println ("Error, cannot instantiate component");
  }
  
  ...
  
  // delete the component instance
  try {
    creationPort.deleteInstance (cid);
  } catch (InstantiateException excep) {
    System.out.println ("Error, cannot destroy component");
  }
  
  // Release the creation service uses port once you are done with using it
  services.releasePort("CreationService");
  
  	  

• C++ Example: This example shows C++ code belonging to a CCA component that creates an instance of another component using the in-process instantiation mechanism and later destroys it. It also shows how the component can use the IDS to acquire an environment object usable in a createInstance call.
  

  // Use the component's services object to get a uses port connected 
  // to the creation service.
  CreationService* creationPort = 
                  (CreationService*) services->getPort("CreationService");
  
  // make the component creation url: this example uses
  // 1. in-process as the creation mechanism, it will create the component in the
  //    same address space as that of the creator
  // 2. the target machine portion of the url is empty
  // 3. The component to be created is: "/components/cat/cca/SpLib". This is
  //    the scoped name of the component as maintained by the information
  //    directory service (IDS)
  char* url = "in-process://components/cat/cca/SpLib";
  
  // Get an environment object from the IDS info object that describes the
  // component. Assume that we have already got the info object through operations
  // on the IDS. The getEnvObj function will fill up the returned environment
  // object with name - value pairs appropriate for that component
  EnvObj* env = infoObject->getEnvObj();
  
  // create component
  try {
    ComponentID* cid = creationPort->createInstance(url, env);
  } catch (InstantiateException& excep) {
    cerr << "Error, cannot instantiate component\n";
  }
  
  ...
  
  // Delete the component instance. This will NOT delete the cid pointer.
  try {
    creationPort->deleteInstance (cid);
  } catch (InstantiateException& excep) {
    cerr << "Error, cannot destroy component\n";
  }
  
  // Release the creation service uses port once you are done with using it.
  services->releasePort("CreationService");
  
  // After you are done with using any pointers returned by the framework
  // services, delete them.
  delete creationPort;
  delete cid;
  delete env;