Introducing AXCIOMA

We base the example on the time honored Echo example application. This example showcases a service that echoes (as return value) a modified version of a string provided as input argument. In our case, a distributed component based example, we will create a component providing an interface offering this service and another component that will use this interface. The component model for this example is shown in Figure 1.

The first thing to do is to design and define the datatypes and interface. In this example we will go for the most simple interaction pattern; synchronous request/reply. In IDL the type definitions look like this.

These IDL definitions are placed in the file echo.idl which we store in a data subdirectory of our project folder according to "AXCIOMA Best Practices".

Figure 2 shows the complete directory tree for this example project. In case of project requiring multiple connectors it is also common to create subdirectories for these too.

Based on the defined datatypes and interfaces for the interaction between our component(s) we can now go about creating the other parts of our implementation like the actual code for the datatypes and interfaces, the connectors and the components. Thanks to the BRIX11 scaffolding tool included with AXCIOMA this will cost us very little effort as well as actual coding. The BRIX11 extensions for supporting AXCIOMA include the AXCIOMA Project Control (APC) commands which allow us to generate large parts of our project implementation infrastructure based on a minimum of meta information provided in APC recipes.

We’re not going to go into the full details of BRIX11 APC at this moment but we will show you the major elements and commands available. For more information you can check out the extensive documentation included in the AXCIOMA distribution package.

The first recipe to create is the project recipe placed in a file called aprc. It’s primary function is to mark the root of the project directory tree and to specify a number of project global settings. For this example project we create the following project recipe.

This specified the data subdirectory as a common include directory for IDL compilation tasks.

Next thing we do is create a connector recipe for the implementation of our chosen synchronous request/reply interaction pattern for the Echo interface. The implementation of choice is a CORBA connector so we create the following connector recipe in the file connectors/echo_corba_conn.aprc.

This specifies a connector recipe named echo_srr which is to use (include) the IDL file echo.idl (to be found by searching any defined IDL include paths like the one specified in the project recipe) to define a CORBA4CCM connector (implementing synchronous request-reply using CORBA) for the Example::Echo interface. The interface type definition must be defined in the scope of the included IDL file(s). In AXCIOMA this is all that is needed to create a completely implemented connector as you will see later on!

Going on we move to creating a component recipe for the component providing the echo service. This recipe will be placed in the file components/echo_provider/echo_provider.aprc.

This specifies a component recipe named echo_provider for a component using the IDL file echo.idl. You may notice there is no mention of an IDL file defining the interface of the component. This is because BRIX11 APC recipes allow the definition of that interface in the recipe through the comp.define …​ construct. This recipe definition directs BRIX11 APC to generate an appropriate IDL file when needed. In this case that would be an IDL file named echo_provider.idl including a definition for a component EchoProvider in the module Example having a single provider port definition do_echo with interface type Example::Echo. The generated IDL will look like this.

BRIX11 APC also supports component recipe definition based on user defined component IDL. More information concerning this feature can be found in the documentation provided with AXCIOMA.

And finally we create a component recipe for the component using the echo service. This recipe will be placed in the file components/echo_user/echo_user.aprc.

This specifies a component recipe named echo_user for a component using the IDL file echo.idl and defines an interface for the component with a single receptacle port use_echo with interface type Example::Echo. The generated IDL for this component will look like this.

After creation of the type IDL file and the BRIX11 APC recipes our project tree looks like the picture shown in Figure 3.

Notice that up to this moment we only defined our interfaces (and datatypes) in IDL and described the basic properties of our components and connectors using fairly simple recipe directives.

In AXCIOMA that is all it takes to be able to start a new project because the BRIX11 APC commands are able to fill in the required blanks and generate all other information/files required for your project after which you will have only relatively little coding left to do to complete your components as you will see in the next section.

To make sure we can see this example actually doing something we will need to add some "business logic" to the components.

First is the provider component. Here we need to add code to the single method of the facet executor for the Example::Echo interface, the process method.

For this example we’ll add some logging to let an observer know that the method was called and showing the input argument. Additionally we’ll construct an answer string from a standard prefix and the input string. The resulting code is shown below.

Our (simple) implementation replaced the default generated placeholder code which was originally between the regeneration markers and will now be preserved whenever the executor files are regenerated.

The CIAOX11_TEST_INFO logger stream is a special logstream provided for easy testing purposes. To use it we need to include a standard header from AXCIOMA. For this purpose there exists a regen section at the head of the echo_provider_exec.cpp where we insert the include as follows.

Again we simply replace the placeholder code between the markers to protect our include declaration against regeneration.

This is all the user supplied coding needed for this simple example to finish the provider component. All the (default) code for supporting the AXCIOMA infrastructure has been generated and does not need any changes in this case.

Now that we have taken care of the echo_provider component we turn our attention to the echo_user component where we need to add some code to actually send a process request through its connected Example::Echo receptacle port.

Again, since this is a very simple example, we use the simplest solution possible and add the code to the standard component executors ccm_activate callback. This is part of the standard component lifecycle events that get triggered by the AXCIOMA component management framework for deployed components. In case of the ccm_activate event we are at a deployment stage where we are sure the components are configured and connected.

Our inserted code looks like this.

Again we use some logging to provide feedback to the casual observer. Like with the provider component we use the CIAOX11 test logger for this and therefor have to include the same standard header which we can insert at a similar location as before.

As with the provider component this is all the user supplied coding required for finishing this component for this simple example.

Re-executing the brix11 apc build command will update the binary artifacts and than we are ready to deploy!

A component based distributed application like this AXCIOMA example does not provide a single execution point like a monolithic application (or even two like a more "classic" client/server application) but instead requires an orchestrated deployment process involving multiple executables and a deployment plan (although AXCIOMA provides various options making the "orchestration" less stringent). We will not go into details concerning the deployment process and deployment plans at this point. More information can be obtained from the documentation included in the AXCIOMA distribution.

For this simple example application we need a script to execute the deployment process as well as deployment plan to direct said process. We can easily derive these from the multitude of examples and tests included in the AXCIOMA distribution and place them in the descriptors subdirectory of the project tree.

In addition to the standard OMG D&C XML based deployment plans AXCIOMA also supports a custom, simpler and better humanly readable declaration format. We use this format to define a deployment plan according to our original model at the start of this text. The result is shown below.

As you can see this deployment plan describes the deployment of the EchoProvider component (a single instance thereof) on the first node (Node1) together with an instance of the CORBA connector for the Example::Echo interface connecting the do_echo facet of the EchoProvider component to the (standard) receptacle of the CORBA connector.

Likewise the plan describes the deployment of the EchoUser component (a single instance thereof) on the second node (Node2) together with an instance of the CORBA connector for the Example::Echo interface connecting the use_echo receptacle of the EchoUser component to the (standard) facet of the CORBA connector. Additionally at this point the plan describes the connection of the (standard) facet of the CORBA connector for the EchoProvider to the (standard) receptacle of the CORBA connector for the EchoUser thereby completing the connection chain between the two component instances.

We copied (and adapted) one of the test execution scripts from the AXCIOMA distribution and placed this in the file descriptors/run_test.pl. Executing this script deploys the application according to the deployment plan described above, provides it some time (seconds) to perform its function and then shuts the deployment down (controlled). Executing the following command from within the descriptors directory will run the script.

The output should look like this.

You have now designed, implemented and run your very first AXCIOMA. Easy does it!

All code for this example can be found at GitHub.