Articles     Forum     Examples     Download     Open Source

Getting Started with PocoCapsule/IoC

Ke Jin

ke-jin.blogspot.com

Oct 17, 2007

Copyright(c) 2007 by Pocomatic Software. All Rights Reserved.

PocoCapsule/IoC is an inversion of control (IoC) (a.k.a dependency injection) component framework. It sets up applications based on user provided declarative descriptions. Such descriptions outline intended application structures (including involved components, their instantiation methods, post-instantiation methods, lifecycle control, and dependencies) without imperatively specifying how to construct these structures step-by-step. The framework and its declarative scenario allow application developers and domain users to focus on business logic implementations without concerns of low level plumbing complexities. 

Through two examples, this tutorial article illustrates that how plain-old C/C++ object instances, instantiation methods/arguments, post-instantiation operations, lifecycle control attributes, and dependency wirings can be expressed in the core XML declarative schema of PocoCapsule IoC framework. Source code, makefile(s), and README html pages of these two examples, as well as nearly 27 other examples, can all be found in the examples directory of a PocoCapsule installation.

The Hello Example – POCO components and IoC invocations

In the first example (examples/basic-ioc/hello), several simplest forms of C++ object manipulations by PocoCapsule framework are presented, starting from the following three:

• C++ object (bean) instantiation, using the C++ constructor of the declared class type,
• Post-instantiation configuration: on a declared member function of the just instantiated object (bean),
• C++ object lifecycle control, using a declared destroy-method. In this example, this method is declared as the delete operator, hence, implies the the destructor of the object class.

The POCO component 

PocoCapsule is neutral to component programming models. This means that it does not dictate a few predefined classes to be types or parent types of components. Instead, virtually all plain old C/C++ objects (POCOs) are valid components. Examples of these POCOs include instances of arbitrary user defined classes, template classes, K&R structs, unions, arrays, and even function pointers. In this hello example, the type of the to be instantiated object (bean) is a plain old C++ class Foo, declared in the header file foo.h as follows:

This class has a constructor, a destructor and a non-static member function hello(). This Foo class is implemented in the source file foo.C as follows:

This source file is compiled and linked into a UNIX shared library or a Windows DLL named as, for instance, foo.so or foo.dll in this example.

Note: Although in this particular example, the component class Foo is declared in a header file, implemented in a separated source file, and then built into a shared library, PocoCapsule/C++ actually does not mandate this partition. With PocoCapsule,

• Multiple components can be declared in one header file,
• Components can be implemented inline in the header file,
• Multiple components can be implemented in one source code file and,
• Multiple components can be built into a dynamic library of arbitrary name,
• Components implementations can also be compiled into static library(ies) and built (linked) into application executable explicitly.

The application description

Then, to construct an application from this Foo class, an application description is orchestrated that expresss the following arrangement:

• An object (bean) of class Foo is to be instantiated using its constructor, with a string "Foo constructor!" as input argument.
• The instance of above bean is under life-cycle control, and to be destroyed using the "delete" operator, hence the destructor, by life cycle manager.
• A post-instantiation IoC invocation for this bean is declared, with "hello" as the method name and a string "Foo hello()!" as input argument.

Also, this example assumes the binaries of Foo class implementation and its dynamic invocation proxies are not linked in the runtime environment but to be dynamically loaded as follows:

• The container should first load the foo.so or foo.dll library (therefore, the $dll, to be substituted accordingly).
• Then, the container should load the reflx.so or reflx.dll library. This is the library containing dynamic invocation proxies of Foo class. These proxies are built from PocoCapsule/C++ framework development tools.

The XML document (setup.xml) of this application description looks like follows:

The dynamic invocation proxies

There is a gap between the component-neutral (i.e. non-invasive) IoC container and container-agnostic plain-old C++ components. In Java IoC containers, this gap is closed using the Java reflection. In C++, there are many ways to skin the same cat. For instance, certain tools (such as gcc-xml and CERN's Reflex) can parse component implementation header files and generate reflection code. Although there are a few insignificant advantages, this approach is more trouble than it's worth. The major problems are a) massive code generation b) bloated runtime footprint, c) easy to be defeated by source code containing non-standard extensions.

PocoCapsule uses an opposite approach. Instead of parsing component header files and generating reflections for all encountered methods regardlessly, PocoCapsule instrument utility pxgenproxy parses the actual application descriptions and only generates dynamic invocation proxies of newly encountered IoC methods. This scenario is a reverse of reflection and therefore is referred to as projection (see further discussion on Reflection from Projection).

Hence, in PocoCapsule, dynamic invocation proxies of the application in this example are generated using the PocoCapsule/C++ instrument utility pxgenproxy from the application description file setup.xml as follows:

The generated source code of proxies will be written out to a file that is named as setup_reflx.cc in this example (the "reflx" stands for REFLection-proXies). This file should be compiled and then linked into a shared/dynamic library (e.g. reflx.so or reflx.dll). If there is any error in the application description against the bean class function prototypes, it will be caught and reported during the compiling and linking stages instead of at runtime deployment.

A mini container

A PocoCapsule/C++ IoC container is a runtime library that is expected to be embedded in user application executables. This example uses such a mini container application executable (main.C) as follows (error handling code has been left-out for simplicity):

This code is compiled and linked with PocoCapsule/C++ runtime (the libpococapsule.so or pococapsule.dll) into an executable file (named as main on Unix/Linux or main.exe on Windows in this example). In executing this application, what will happen are:

• The POCO_AppContext::create() method in the code reads/parses the input application description file (the setup.xml in this case). This will cause all <load> in the description to be performed.
• The POCO_AppContext::initSingletons() method next after the create() instantiates all beans of lazy-init attribute equals "false" (referred to as eager beans), and performs their post-instantiation ioc invocations.
• The POCO_AppContext::terminate() method will release all singleton bean instances that have been put under the container’s life-cycle control, namely have their destroy-method attribute specified.
• The POCO_AppContext::destroy() method releases resources of the application context.

Notably, the container and IoC runtime on the upper portion of this diagram do not depend on either the dynamic invocation proxies or application business logic POCO implementations in the lower portion. When proxies are loaded up, they register themselves to the IoC container runtime and will be used in a scenario similar to Java reflection.

Start the application

Because the mini container of this example is hardcoded to create an application context from the setup.xml, therefore, on starting the above mini container executable, the application described in setup.xml will be set up. To be specifically, on calling the initSingletons() of the application context, the declared eager singleton bean of class Foo will be instantiated. Then, the post-instantiation IoC method hello() will be invoked afterwards. This method prints out the text “Hello Foo hello()!”.  On the terminate() of the context, the singleton’s destroy method will be invoked which calls the destructor of the Foo class, that in turn prints out the text “That’s all folks! Goodbye!” These results are shown as follows:

Calling stdio printf() and << operator on std::cout

The other two IoC invocation scenarios illustrated in this example declare invocations on the C stdio printf() global function and then, the << operator on std::cout. To do this, a new bean is declared with two post-instantiation <ioc> elements (in the setup.xml).

The following details in this new application description are notable:

• The class attribute of the additional bean is "void". This implies all post-instantiation <ioc> methods on this bean are global or static C or C++ functions (without the hidden C++ this pointer).
• This bean does not have its lazy-init attribute declared "false", it is not going to be instantiated explicitly by initSingletons() on the application context.
• However, the previous declared eager bean of Foo class is now declared to depend-on this "void" bean. This means, before initSingletons() instantiate the Foo class bean, it is going to first instantiate this "void" bean, even if it is declared after the Foo class bean.

The two post-instantiation <ioc> elements describe the following operations:

• Calling the global stdio C function printf() with the strings "Hello %s\n" and "C stdio printf()!" as the first and the second arguments.
• Calling the << operator on std::cout, with the string "Hello C++ std::cout!\n" as the argument.

The method attribute of the second <ioc> element is "std::cout {{". This is a user friendly equivalence of the "std::cout &lt;&lt;". PocoCapsule/C++ engine will convert it to "std::cout <<".

Because the application description in setup.xml introduces new kinds of IoC invocations, the proxy library should be regenerated to include proxies for these new signatures. The pxgenproxy instrument utility is used again as follows:

The -h option indicates a user-defined header file, and -H option indicates a standard library or compiler environment defined header.

Like before, the source code of IoC proxies will be written to setup_reflx.cc. Compiling and linking them also into the reflx.so or reflx.dll, then, it is ready to be used by the container.

The mini container built and used previously does not need to be modified and rebuilt, as it does not depend on bean implementation or application description content change. 

Running the same mini container executable again, with the new application description in setup.xml, the deployment process will print out the following result:

2.1.7 Tracing IoC invocations

This example can be found in the examples/basic-ioc/hello directory of a PocoCapsule installation, with more features enabled. For instance, if the main executable started with the command line argument "-Dpococapsule.trace.enable=true", it will print out the process of IoC invocations to stderr as follows (high lighted. The outputs to stdout from the application itself are low lighted):

The GPS Example – Dependency Injection

The example presented in previous section is trivial and does not involve dependency among beans (except for the life-cycle dependency). The example to be presented next has three components that have dependencies, especially circular dependencies. Source code, Makefile and README.html of this example are located in the examples/basic-ioc/gps directory of a PocoCapsule installation.

The GPS instrument and its component devices

This example models a GPS device that comprises of the following three components (as they are illustrated by the diagram in the next page):

• A tick pulse generator implemented as the TickGenImpl class that generates clock pulses for the instrument,
• A GPS location component implemented as the GPSLocatorImpl class that determines the instrument’s current location and notifies subscribed display device on any position change.
• A display component implemented as the NavDisplayImpl class that retrieves location data from GPS device on receiving position change notification, and displays the new position.

The detail interface/operation signatures and implementation of these POCO components are non-critical in comprehending the IoC deployment technique, and therefore are left out, and can be found in the examples/basic-ioc/gps directory of a PocoCapsule installation.

These three components are built into three shared libraries, TickGenImpl.so/dll, GPSlocatorImpl.so/dll and NavDisplayImpl.so/dll, and are all independent of the PocoCapsule/C++ in terms of source code, binaries and runtime.

Although these three components have dependencies, they do not have coupling of one implementation to others or to their factories. The implementation class of any of these components can be changed without affect others, as long as the new class still supports the required interface (e.g. inherits the required super class). The IoC container is now functioning as the object factories. Change implementation class is merely an easy change of the application description.

Note: Although in this particular example, components are implemented in separated source files and built into separate libraries named after their class names, PocoCapsule/C++ does not mandate how component implementations are partitioned into source code and libraries, and how libraries are named. With PocoCapsule,

• Multiple components can be declared in one header file,
• Multiple components can be  implemented in one source code file and,
• Multiple components can be built into the one dynamic or static library of arbitrary name.

The application description

The application description for this example declares the following configuration of the modeled GPS device:

• Loading all shared/dynamic libraries of the above three components, as well as the library of reflection proxies. Library loading has higher deployment precedence than others in this example, and will be performed initially regardless where they were declared in this description.
• An eager singleton bean of class TickGemImpl is declared and is assigned with the id "tick-gen". The declared instantiation method is the class's container with two short integers as input arguments.
• A post-instantiation IoC invocation of method subscribe() is declared for the bean above. This method takes the reference of another bean of id "gps-locator" as input argument. By default, that bean will be passed as a pointer of its declared class type (namely, value of its class attribute). For instance, in this case, it will be passed as a GPSLocatorImpl*. This so-called "dependency injection" wires the "callee" bean gps-locator to this "caller" bean tick-gen.
• A lazy singleton bean of class GPSLocatorImpl is declared and is assigned with the id "gps-locator". As a lazy bean, this bean will be instantiated on demand, such as when it is referred as an input argument somewhere else. This bean is declared to be instantiated using its constructor with no argument.
• A post-instantiation IoC invocation of method subscribe() is declared for the bean above. This method takes one input argument which is the reference of another bean with id "nav-display". Similarly, in this case, the "callee" bean will be injected as a NavDisplayImpl* argument.
• A lazy singleton bean of class NavDisplayImpl is declared and is assigned with the id "nav-display". Similar, this bean will also be instantiated on demand. The declared instantiation method is the class’s constructor with the reference of the bean of id "gps-locator" as the input argument. In this case, the argument type is GPSLocatorImpl*.

The declaration above not only declared three bean instances, but also wired them in circular dependency as illustrated in the following diagram:

The XML document (named as setup.xml in this example) of the application descriptionabove looks like follows:

Generating dynamic invocation proxies

Similarly, the dynamic invocation proxies required by the container reflection engine are generated using the PocoCapsule/C++ instrument utility pxgenproxy from the application description file setup.xml as follows:

Similar to the previous example, the source code of IoC proxies will be written to the setup_reflx.cc. Compiling and linking them into the reflx.so or reflx.dll file again, then, it is ready to be used by the container.

Running the example

The mini container built and used previously in the Hello example can be reused here without any source code change or rebuild, as it is independent of bean implementations or contents of application descriptions . 

Running the mini container executable main (or main.exe) again, the application will print out the following results:

IoC beyond a "lousy constructor"

These two IoC examples are straightforward and even seem to be nothing significant. One would wonder what was the benefits of this technique. Indeed, IoC was thought to be no more than a simple old design pattern/principle, a lousy way of wiring components through dependency injection, or something merely about unit test and "test driven development".

This question is answered in the "Why and What of IoC" and the "Domain Specific Modeling in IoC frameworks". It will become clear that the seamless combination of non-invasive IoC and declarative Domain Specific Modeling (DSM) reveals a software development paradigm shift.  

Back to the PocoCapsule article page

This page has been visited:

free hit counter html code