3.3. Inserting Implementations into Bocca-Generated Components

3.3. Inserting Implementations into Bocca-Generated Components
	Chapter 3. Using Bocca: An Application Generator for CCA

So far, with very little work, we have generated what appears to be an application but is really just the componentized shell of an application. In order to cause it to do something useful we have to add the implementation. There are two places that we have to change things to make that happen: add methods to the interface definitions (.sidl file) and then put the implementation code into the components in the language chosen in Section 3.1, “ Creating a Bocca Project ”. Bocca manages the many files required and produced by Babel, tracking each file's location so you do not need to.

How to edit and find files in bocca projects

Because bocca generates all the files in the project, it knows where they are and will help you apply your favorite editor to them. It is important to use bocca edit, because after you exit the editor bocca regenerates all other source files that depend on the source file edited.


# edit the sidl file of the symbol
$  bocca edit SIDL_SYMBOL

# edit the header/module of the component
$  bocca edit -m SIDL_CLASS

# edit the implementation file of the class or component
$  bocca edit -i SIDL_CLASS

# edit the named method in the class or component if your editor supports +N
$  bocca edit -i SIDL_CLASS method

Replace edit with whereis in any of the above, and bocca prints out the path of the file that would be edited without starting up an editor.

The environment variable BOCCA_EDITOR (and if that is not set, then EDITOR) controls what editor gets invoked by bocca edit. Users of emacs may want to set BOCCA_EDITOR to "emacs -nw" when editing on a remote cluster with slow or no X11 connections.

All emacs and vi versions support +N, which is used for specifying the initial position in the file when a method name is specified. If your favorite editor does not support +N, omit the method name and search for it in the opened file using your editor's search capability.

Bocca also has a way for you to tell it you've edited a file by some means other than bocca edit.


# something was done to FunctionPort. Update its dependencies, if any.
$  bocca edit --touch FunctionPort

# something was done to Driver code. Update its dependencies, if any.
$  bocca edit --touch -i Driver

If you do not tell bocca, you may find methods you just added to a .sidl file missing from the implementation when you edit that.

3.3.1. Adding Methods to Ports

First modify the SIDL files to create the gov.cca.Ports that are needed to import/export functionality from/to the components. Remember to set the BOCCA_EDITOR environment variable to your favorite editor, per How to edit and find files in bocca projects, if you do not like the default editor bocca finds in your environment.


$  bocca edit IntegratorPort



// DO-NOT-DELETE bocca.splicer.begin(myProject.comment)

// Insert-UserCode-Here {myProject.comment} (Insert your package comments here)

// DO-NOT-DELETE bocca.splicer.end(myProject.comment)
package myProject version 0.0 {

    // DO-NOT-DELETE bocca.splicer.begin(myProject.IntegratorPort.comment)

    // Insert-UserCode-Here {myProject.IntegratorPort.comment} (Insert your port comments here)

    // DO-NOT-DELETE bocca.splicer.end(myProject.IntegratorPort.comment)
    interface IntegratorPort extends gov.cca.Port
    {
        // DO-NOT-DELETE bocca.splicer.begin(myProject.IntegratorPort.methods)

        // Insert-UserCode-Here {myProject.IntegratorPort.methods} (Insert your port methods here)

        // DO-NOT-DELETE bocca.splicer.end(myProject.IntegratorPort.methods)
    }
}

Insert the integrate method:



// DO-NOT-DELETE bocca.splicer.begin(myProject.comment)

// Insert-UserCode-Here {myProject.comment} (Insert your package comments here)

// DO-NOT-DELETE bocca.splicer.end(myProject.comment)
package myProject version 0.0 {

    // DO-NOT-DELETE bocca.splicer.begin(myProject.IntegratorPort.comment)

    // Insert-UserCode-Here {myProject.IntegratorPort.comment} (Insert your port comments here)

    // DO-NOT-DELETE bocca.splicer.end(myProject.IntegratorPort.comment)
    interface IntegratorPort extends gov.cca.Port
    {
        // DO-NOT-DELETE bocca.splicer.begin(myProject.IntegratorPort.methods)



    double integrate(in double lowBound, in double upBound, in int count);



        // DO-NOT-DELETE bocca.splicer.end(myProject.IntegratorPort.methods)
    }
}

Quit the editor after you are done editing. bocca edit then finishes by updating the components that depend on the port edited:



Updating makefiles (for myProject.IntegratorPort, myProject.Driver, myProject.Integrator)...
Using Babel to validate the SIDL for port myProject.IntegratorPort ...
Updating the cxx implementation of component myProject.Driver ...
Updating the cxx implementation of component myProject.Integrator ...
$

Next edit the file FunctionPort.sidl:


$  bocca edit FunctionPort



// DO-NOT-DELETE bocca.splicer.begin(myProject.comment)

// Insert-UserCode-Here {myProject.comment} (Insert your package comments here)

// DO-NOT-DELETE bocca.splicer.end(myProject.comment)
package myProject version 0.0 {

    // DO-NOT-DELETE bocca.splicer.begin(myProject.FunctionPort.comment)

    // Insert-UserCode-Here {myProject.FunctionPort.comment} (Insert your port comments here)

    // DO-NOT-DELETE bocca.splicer.end(myProject.FunctionPort.comment)
    interface FunctionPort extends gov.cca.Port
    {
        // DO-NOT-DELETE bocca.splicer.begin(myProject.FunctionPort.methods)

        // Insert-UserCode-Here {myProject.FunctionPort.methods} (Insert your port methods here)

        // DO-NOT-DELETE bocca.splicer.end(myProject.FunctionPort.methods)
    }
}

Add two methods init and evaluate so that FunctionPort looks like this:



// DO-NOT-DELETE bocca.splicer.begin(myProject.comment)

// Insert-UserCode-Here {myProject.comment} (Insert your package comments here)

// DO-NOT-DELETE bocca.splicer.end(myProject.comment)
package myProject version 0.0 {

    // DO-NOT-DELETE bocca.splicer.begin(myProject.FunctionPort.comment)

    // Insert-UserCode-Here {myProject.FunctionPort.comment} (Insert your port comments here)

    // DO-NOT-DELETE bocca.splicer.end(myProject.FunctionPort.comment)
    interface FunctionPort extends gov.cca.Port
    {
        // DO-NOT-DELETE bocca.splicer.begin(myProject.FunctionPort.methods)



    void   init(in array<double,1> params);
    double evaluate(in double x);



        // DO-NOT-DELETE bocca.splicer.end(myProject.FunctionPort.methods)
    }
}

Again quit the editor and the dependent components are updated as indicated by this output from bocca edit:



Updating makefiles (for myProject.FunctionPort, myProject.Integrator, myProject.Function)...
Using Babel to validate the SIDL for port myProject.FunctionPort ...
Updating the cxx implementation of component myProject.Integrator ...
Updating the cxx implementation of component myProject.Function ...
$

What we have done is place methods into the SIDL files in a language-independent way. When you type make all of the the new method information is propagated to the language-dependent implementation files. Of course the methods will be unimplemented but the components will build anyway. So let's do that now:



$  make; make check





# =======================================================================
# No SIDL files in external/sidl, skipping build for external
# =======================================================================

# =======================================================================
# Building in ports/, languages: cxx
# =======================================================================
## Building ports...

[c] using Babel to generate cxx client code for myProject.FunctionPort...
[c] creating library: libmyProject.FunctionPort-cxx.la...
[c] using Babel to generate cxx client code for myProject.IntegratorPort...
[c] creating library: libmyProject.IntegratorPort-cxx.la...
# =======================================================================
# Building in components/clients/, languages: cxx
# =======================================================================
## Building clients...

# =======================================================================
# Building in components/, languages: cxx
# =======================================================================


[s] Building component myProject.Driver:
[s] using Babel to generate cxx implementation code from myProject.Driver.sidl...
[s] compiling sources...
[s] creating component library: libmyProject.Driver.la ...
[s] finished libtooling: components/myProject.Driver/libmyProject.Driver.la ...
[s] creating Ccaffeine test script (components/tests/instantiation.gen.rc)...

[s] Building component myProject.Function:
[s] using Babel to generate cxx implementation code from myProject.Function.sidl...
[s] compiling sources...
[s] creating component library: libmyProject.Function.la ...
[s] finished libtooling: components/myProject.Function/libmyProject.Function.la ...
[s] creating Ccaffeine test script (components/tests/instantiation.gen.rc)...

[s] Building component myProject.Integrator:
[s] using Babel to generate cxx implementation code from myProject.Integrator.sidl...
[s] compiling sources...
[s] creating component library: libmyProject.Integrator.la ...
[s] finished libtooling: components/myProject.Integrator/libmyProject.Integrator.la ...
[s] creating Ccaffeine test script (components/tests/instantiation.gen.rc)...

[s] Building component myProject.emptyComponent: doing nothing -- library is up-to-date.

Build summary:
SUCCESS building myProject.Driver
SUCCESS building myProject.Function
SUCCESS building myProject.Integrator

### To test instantiation of successfully built components, run 'make check' ###

################ Finished building everything #################
####### You can run some simple tests with 'make check' #######

make --no-print-directory --no-builtin-rules -C components check

### Test library load and instantiation for the following languages: cxx
Running instantiation tests only
Test script: /data/user1/myProject/components/tests/instantiation.gen.rc
SUCCESS:
==> Instantiation tests passed for all built components (see /data/user1/myProject/components/tests/instantiation.gen.rc.log).
make --no-print-directory --no-builtin-rules check-user
$

The methods you inserted in SIDL have now been inserted into your already generated components using the language you chose when you created the project or each component in Section 3.1, “ Creating a Bocca Project ”. At this point we are ready to insert the actual implementation into the bodies of these methods. You must now jump to the particular language implementation you chose in Section 3.1, “ Creating a Bocca Project ”. There is (or soon will be) a section below for each language choice available in bocca. While it is not surprising that we have to write code in a specific programming language to implement a component's functionality, it is rather remarkable that an entire application skeleton can be created, built, and run without writing code in a language other than SIDL.


3.2. Creating Ports and Components		3.4. Language-Specific Implementations of the Function, Integrator, and Driver Components