...

...

<?xml version="1.0" encoding="UTF-8"?>

...

<TestPowerSupplyACS xmlns="urn:schemas-cosylab-com:PowerSupplyACS:1.0"

...

    xmlns:cdb="urn:schemas-cosylab-com:CDB:1.0"

...

    xmlns:baci="urn:schemas-cosylab-com:BACI:1.0"

...

    xmlns:powerSupply="urn:schemas-cosylab-com:PowerSupply:1.0"

...

    xmlns:testPowerSupply="urn:schemas-cosylab-com:TestPowerSupplyACS:1.0"

...

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

...

  <current xmlns="urn:schemas-cosylab-com:TestPowerSupplyACS:1.0"/>

...

  <readback xmlns="urn:schemas-cosylab-com:TestPowerSupplyACS:1.0"/>

...

  <status xmlns="urn:schemas-cosylab-com:TestPowerSupplyACS:1.0"/>

...

</

...

PowerSupplyACS>

...

A simple example: the mount.

We are aware that the power supply example is a bit complicated because we wanted to show how to override some of the default values for the properties. In the acsexmpl module there are several different examples. We briefly show also the case of the CDB configuration files for the mount component example. The mount has for read-only double properties, as you can read in its IDL definition file.
The schema for the mount component See acsexmple/ws/config/CDB/schemas/MOUNT.xsd. is:
1

<?xml version="1.0" encoding="UTF-8"?>

...

<xs:schema

...

 targetNamespace="urn:schemas-cosylab-com:MOUNT:1.0"

...

 xmlns:xs="http://www.w3.org/2001/XMLSchema"

...

 xmlns="urn:schemas-cosylab-com:MOUNT:1.0"

...

 xmlns:cdb="urn:schemas-cosylab-com:CDB:1.0"

...

 xmlns:baci="urn:schemas-cosylab-com:BACI:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified">

...

 <xs:import namespace="urn:schemas-cosylab-com:CDB:1.0" schemaLocation="CDB.xsd"/>

...

 <xs:import namespace="urn:schemas-cosylab-com:BACI:1.0" schemaLocation="BACI.xsd"/>

...

 <xs:complexType name="MOUNT">

...

 <xs:sequence>

...

     <xs:element name="cmdAz" type="baci:ROdouble"/>

...

     <xs:element name="cmdEl" type="baci:ROdouble"/>

...

     <xs:element name="actAz" type="baci:ROdouble"/>

...

     <xs:element name="actEl" type="baci:ROdouble"/>

...

   </xs:sequence>

...

  </xs:complexType>

...

  <xs:element name="MOUNT" type="MOUNT"/>

...

</xs:schema> 

As expected, the xml defining each component is also very simple:
1

<?xml version="1.0" encoding="UTF-8"?>

...

<MOUNT xmlns="urn:schemas-cosylab-com:MOUNT:1.0"

...

       xmlns:baci="urn:schemas-cosylab-com:BACI:1.0"

...

           xmlns:cdb="urn:schemas-cosylab-com:CDB:1.0"

...

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

...

  <cmdAz />

...

  <cmdEl />

...

  <actAz />

...

  <actEl />

...

</MOUNT>

...

...

Header files

(If you are using ALMA directory structure, header files should be located in the <xxxx>/ws/include or <xxxx>/include directory).
Let us now create the C++ header file for the device server. Later, this file has to be included in the implementation file (.cpp). There is not much to do here – you first have to write a standard file header and then make the corresponding "#include"s for all of the properties you will use (note: code marked with *bold should be adapted for new applications):
#ifndef

#ifndef acsexmplPowerSupplyImpl_h

...

#define acsexmplPowerSupplyImpl_h

...

 
#ifndef __cplusplus

...

#error This is a C++ include file and cannot be used from plain C

...

#endif

...

 
#include <baciCharacteristicComponentImpl.h>

...

 
#include <acsexmplExport.h>

...

#include <acsexmplPowerSupplyS.h>

...

 
#include <baciROdouble.h>

...

#include <baciRWdouble.h>

...

#include <baciROpattern.h>

...

 
#include <baciSmartPropertyPointer.h>

...

 
using namespace baci;

For ACS Component with characteristic or properties usage, the baciCharacteristicComponentImpl.h file is needed. acsexmplExport.h is used for exporting this example to the Microsoft Windows environement. Also, acsexmplPowerSupplyS.h is automatically generated with tao_idl (it has the same name as the IDL with an "S" appended at the end) and header files for all properties that are used (baciROdouble.h and baciROpattern.h) must be included.
The baciSmartPropertyPointer.h file includes the declaration for the smart pointers. They help to write the component in a clear and reliable way. The following example is written using smart pointers but it is also possible to use the properties without even if we suggest using the smart pointers with properties.

#define ON_ACTION    0

...

#define OFF_ACTION   1

...

#define RESET_

...

ACTION2
 
/**
 * The class PowerSupply simulates the behaviour of a power supply.
 * (…doxygen comment…)
 */
classacsexmpl_EXPORT PowerSupply:public virtual CharacteristicComponentImpl,
                                  public virtual POA_PS::PowerSupply,

...

                                  public ActionImplementator
{

Asynchronous call handling implementation requires that action numbers are defined for each call (here on(), off() and reset()).

PowerSupply must inherit from the class CharacteristicComponentImpl because the IDL interface does, ActionImplementator for asynchronous methods, and POA_<name of module in IDL>::<name of interface in IDL> which is auto-generated by tao_idl. The CharacteristicComponentImpl class incorporates standard methods and macros necessary for the CORBA interface implementation and MACI-DLL support.

Now we can define public methods and fields (note: because of inheritance, you should put virtual before the destructor and other methods):

public:

...

 
    /**
     * Constructor
     * @param poa poa which will activate this and also all other COBs 
     * @param name Component name
     */
    PowerSupply(const ACE_CString& name, maci::ContainerServices* containerServices);

...

 
    /**
     * Destructor
     */
    virtual ~PowerSupply();
 
    /**
     * Override component lifecycles method
     */
    virtual void 

...

execute

...

() throw (acsErrTypeLifeCycle::LifeCycleExImpl);

...

 
    /* --------------- 

...

[ Action implementator interface 

...

] -------------- */

...

 
    /**

...

     * Action dispatcher function – called from a method inherited from 
     * ActionImplementator class whenever there is an asynchronous method waiting in a
     * queue.
     * (…doxygen comment…)
     */
     virtual ActionRequest 
     invokeAction(int function, BACIComponent* cob_p, const int& callbackID, 
                  const CBDescIn& descIn, BACIValue* value, Completion& completion, 
                  CBDescOut& descOut);
 
    /***
     * Implementation of async. on() method – called by invokeAction 
     */
    virtual ActionRequest 
    onAction(BACICComponent* cob, const int& callbackID, const CBDescIn& descIn, 
             BACIValue* value, Completion& completion, CBDescOut& descOut);
 
    /***
     * Implementation of async. off() method – called by invokeAction
     */
    virtual ActionRequest 
    offAction(BACICComponent * cob, const int& callbackID, const CBDescIn& descIn, 
              BACIValue* value, Completion& completion, CBDescOut& descOut);
 
    /**
     * Implementation of async. 

...

reset

...

() method 

...

– called by invokeAction
     */
    virtual ActionRequest 
    

...

resetAction(BACICComponent * cob, const int& callbackID, const CBDescIn& descIn, 
                BACIValue* value, Completion& completion, CBDescOut& descOut);

...

...

 
    /* --------------------- 

...

[ CORBA interface 

...

] ----------------------*/
        

...

    /**

...

     * Switches on the power supply – registers the call to the asynch. queue
     * (…doxygen comment…)
     */    
    virtual void 
    on(ACS::CBvoid_ptr cb, const ACS::CBDescIn &

...

 desc)
        throw(CORBA::SystemException);

...

  
    /**

...

     * Switches off the power supply - registers the call to the asynch. queue
     * (…doxygen comment…)
     */ 
    virtual void 
    off(ACS::CBvoid_ptr cb, const ACS::CBDescIn & desc)

...

        throw(CORBA::SystemException);

...

  
    /**
     * Resets the power supply - registers the call to the asynch. queue
     * (…doxygen comment…)
     */ 
    virtual void 
    reset(ACS::CBvoid_ptr cb, const ACS::CBDescIn & desc)

...

        throw(CORBA::SystemException);

...

  
    /**

...

     * Property current contains the commanded current of the power supply.
     */ 
    virtual ACS::RWdouble_ptr

...

 
   current()

...

        throw(CORBA::SystemException);

...

  
    /**
     * Property readback is the actual current obtained from the physical device.
     */ 
    virtual ACS::ROdouble_ptr 
    readback()
        throw(CORBA::SystemException);

...

  
    /**
     * Property status contains the statusof the power supply.
     */
    virtual ACS::ROpattern_ptr

...

 
   status()

...

        throw(CORBA::SystemException);

The private fields usually consist of all variables that are in the program. We use a smart pointer for each property. The type of each smart pointer is a template based on the type of the related property. The smart pointers for the properties take care of all the CORBA detail in behalf of the developer making the programming of a device server easier, faster and safer.

private:

...

 
    /// Properties

...

    SmartPropertyPointer<ROdouble> m_readback_sp;

...

    SmartPropertyPointer<RWdouble> m_current_sp;

...

    SmartPropertyPointer<ROpattern> m_status_sp;

...

  
};

...

 
#endif   /* acsexmplPowerSupplyImpl_h */

The execute method is part of the life cycle methods. Ther are four methods for the life cycle. They are defined in acscomponent and can be overridden by

...

the developer.

    virtual voidinitialize()
      throw(acsErrTypeLifeCycle::acsErrTypeLifeCycleExImpl);

...

 
    virtual voidexecute()
      throw(acsErrTypeLifeCycle::acsErrTypeLifeCycleExImpl);

...

     */

...

    virtual voidcleanUp();

...

 
    virtual voidaboutToAbort();

...

The intialize method is called by the container after instantiating the component i.e. after executing the constructor. The developer should insert here all the code related to the initialization of the component like, for example retrieve connections, read in configuration files orparameters, build up in-memory tables and so on. This method is called before any functional requests can be sent to the component.

...

The execute method is called by the container after

...

the initialize to signal that the server has to be ready to accept functional requests.

The developer in

...

the execute and the  initializecan throw an exception to signal a malfunction to the container. In this case the exception is catched by the container and the component will be released and unloaded. 

...

The aboutToAbort is called by the container in case of an error and an emergency sistuation requests the component to be destroyed. The developer should insert here the code to handle this situation trying to release resources and so on. This method is called in an emergency situation and there is no warranty that the container will wait its termination before destroying the component.

Finally,

...

the cleanUp method is called by the container before destroying the server in a normal situation. The developer should release all the reasource and perform all the clean up here.

As a guideline, we suggest to leave the constructor and the destructor of the server empty moving the code in the life cycle method. This should help in writing more reliable servers.

There is no need to call the parent life cycle method 

In the power supply component,

...

 execute is the only life cycle method overridden. 

Together with the life cycle methods there is the concept of the state of the component i.e. the component passes through different states during its life, since it is built until it is destroyed. The state is transparent to the user and managed by the ComponentStateManager object that is part of the ContainerServices. The state of the component is managed by the container and must not be accessed nor modified by the developer. For completeness I report here the states that a component can assume, as defined in acscomponent.idl:

...

Before executing the aboutToAbort method

...

COMPSTATE_DEFUNCT

...

Before destroying the component

...

Implementation files

(If you are using ALMA directory structure, implementation files should be located in <xxxx>/ws/src or <xxxx>/src directory.)
Tao has already generated some files needed for client-server communication, but now we have to implement our device server. I will divide the C++ file into smaller parts and explain each of them. The beginning of the program is pretty much standard, so I will just write about unusual lines. (Note: code marked with bold should be adapted for new applications):

#include <vltPort.h>

...

static char *rcsId="@(#) $Id: $";

...

static void *use_rcsId = ((void)&use_rcsId,(void *) &rcsId);

...

#include <baciDB.h>

...

#include

...

 <acsexmplPowerSupplyImpl.h>

...

using namespace baci;

Now we have to write a constructor:

PowerSupply::PowerSupply(const ACE_CString& name, maci::ContainerServices * containerServices):

...

    CharacteristicComponentImpl(name,containerServices)

...

    m_readback_sp(new ROdouble(name+":readback", getComponent()),this),

...

 
    m_current_sp(new RWdouble(name+":current", getComponent()),this),

...

 
    m_status_sp(this)

...

{
    ACS_TRACE("::PowerSupply::PowerSupply");

...

    // properties

...

    m_status_sp = new ROpattern(name+":status", getComponent());

...

}

\\
\\
\\
The destructor is empty. The entire cleanup for the properties is managed by the smart pointers.
\\
*PowerSupply{*}::~{*}PowerSupply{*}()
\{
\}
\\
Let us come to actions now. All requests for asynchronous actions go through the Activator, which sends this request back to the device server. This is done through the invokeAction() method, where you define what has to be done when a call is received:
 \\
/* --------------- \[ Action implementator interface \] -------------- */
\\
ActionRequest 
PowerSupply::invokeAction(int function, BACIComponent* cob, const int& callbackID,
    const CBDescIn& descIn, BACIValue* value, Completion& completion,
    CBDescOut& descOut) 
\{
  switch (function) 
    \{
    case *ON{*}_ACTION:
      return *on{*}Action(cob, callbackID, descIn, value, completion, descOut);
    case *OFF{*}_ACTION:
      return *off{*}Action(cob, callbackID, descIn, value, completion, descOut);
    case *RESET{*}_ACTION:
      return *reset{*}Action(cob, callbackID, descIn, value, completion, descOut);
    default:
      return reqDestroy;
    \}
\}
\\
\\
The implementation of the functions we defined in the previous method:
\\

1. 
   

   Wiki Markup
   /* ------------------ \[ Action implementations \] ----------------- */

   
   

2. /// implementation of async. on() method
3. ActionRequest
4. PowerSupply::onAction(BACIComponent* cob, const int& callbackID,
5. const CBDescIn& descIn, BACIValue* value,
6. Completion& completion, CBDescOut& descOut)
7. {
8. ACS_DEBUG_PARAM("::PowerSupply::onAction", "%s", getComponent()->getName());
9. ...........
10. completion = ACSErrTypeOK::ACSErrOKCompletion();
11. // complete action requesting done invokation,
12. // otherwise return reqInvokeWorking and set descOut.estimated_timeout
13. return reqInvokeDone;
14. }

...

\\
The offAction() and resetAction() functions are based on the same rule - just replace the name and the part where the device server actually does something.
\\
\\
We have to describe the device server's actions (like on(), off(), reset()). These are asynchronous (usually they take some time and we do not want to block a client while executing) so we have to register the action to the Activator that will then do the rest of the procedure.  For example, calling on() will just register that action inside a queue until Activator calls PowerSupply::invokeAction which will in turn, call onAction().
\\
The client must provide a pointer to it's implementation of callbacks and the structure of type CBDescIn (that identifies the callback) as an argument of the registerAction() method. Our device server sends these parameters to Activator and also adds a pointer to itself and a description of an action (integer - ON_ACTION will be replaced with 1, OFF_ACTION with 2 and so on).
\\
Your job is to write one block of a code for each action and change only the last argument of the method registerAction - an integer which is later sent back to the device server, to the method invokeAction(). First argument of registerAction() method - in this case BACIValue::type_null - is a callback type.
\\
void
*PowerSupply::on* (ACS::CBvoid_ptr cb, const ACS::CBDescIn & desc)
  throw(CORBA::SystemException)
\{
  getComponent()->registerAction(BACIValue::type_null, cb, desc, this, *ON{*}_ACTION);
\}
\\
void
*PowerSupply::off* (ACS::CBvoid_ptr cb, const ACS::CBDescIn & desc)
  throw(CORBA::SystemException)
\{
  getComponent()->registerAction(BACIValue::type_null, cb, desc, this, *OFF{*}_ACTION);
\}
\\
void
*PowerSupply::reset* (ACS::CBvoid_ptr cb, const ACS::CBDescIn & desc)
  throw(CORBA::SystemException)
\{
  getComponent()->registerAction(BACIValue::type_null, cb, desc, this, *RESET{*}_ACTION);
\}
\\
throw(...) defines what kind of exceptions are available.
\\
\\
If a client wants to do something with current, readback, and other properties, it must get a reference to these properties. This is done in following code:
\\
ACS::{*}RWdouble{*}_ptr
*PowerSupply::current{*}()
    throw(CORBA::SystemException)
\{
    if (m_current_sp==0)
        return ACS::{*}RWdouble{*}::_nil();
\\
    ACS::{*}RWdouble{*}_var prop = ACS::{*}RWdouble{*}::_narrow(m_current_sp->getCORBAReference());
    return prop._retn();
\}
\\
ACS::{*}ROdouble{*}_ptr
*PowerSupply::readback{*}()
    throw(CORBA::SystemException)
\{
    if (m_readback_p==0)
        return ACS::{*}ROdouble{*}::_nil();
\\
   ACS::{*}ROdouble{*}_var prop = ACS::{*}ROdouble{*}::_narrow(m_readback_sp->getCORBAReference());
    return prop._retn();
\}
\\
ACS::{*}ROpattern{*}_ptr
*PowerSupply::status{*}()
    throw(CORBA::SystemException)
\{
    if (m_status_p==0)
        return ACS::{*}ROpattern{*}::_nil();
\\
   ACS::{*}ROpattern{*}_var prop = ACS::{*}ROpattern{*}::_narrow(m_status_sp->getCORBAReference());
    return prop._retn();
\}
\\
One must write accessors for every property, changing the name of a property (current), variable (m_current_sp) and type of a property (replace all fields where RWdouble appears with ROdouble or ROpattern).
\\
Now we are really near the end. We have to add MACI DLL support functions. For this purpose we use the macro MACI_DLL_SUPPORT_FUNCTIONS(class_name):
\\
/* --------------- \[ MACI DLL support functions \] -----------------*/
\\
#include <maciACSComponentDefines.h>
MACI_DLL_SUPPORT_FUNCTIONS ({*}PowerSupply{*})
\\
/* ----------------------------------------------------------------*/
\\
As we said at the beginning of the paragraph, it is possible to use the properties without smart pointers even if we discourage this implementation. We briefly describe herein the changes in the previous code if smart pointers were not used.
In the include file each property is defined without the templetized smart pointer type and, of course, the baciSmartPropertyPointer.h is not needed. Note that the names of the variables terminate with _p and not with _sp to highlight that we are now using pointers instead of smart pointers. 
\\
*ROdouble* m_readback_p* 
*ROdouble* m_readback_p;* 
*RWdouble*  m_current_p;*
\\
In the constructor these pointers are first initialized to 0 then each property is created in the same way they are created with smart pointers. The CHARACTERISTIC_COMPONENT_PROPERTY macro must be implemented for each BACI property.  The macro performs error checking and generates a description of the property. This macro must not be used with smart pointers because they take care of all the initializations automatically.
\\
The following is the constructor without using smart pointers for the properties.
\\
*PowerSupply{*}::{*}PowerSupply{*}(const ACE_CString& name,
  maci::ContainerServices * containerServices):
 CharacteristicComponentImpl(name,containerServices),
 *m_readback_p({*}0{*}),*
 *m_current_p({*}0{*}),*
 *m_status_p({*}0{*}) \{*
 m_readback_p = new *ROdouble{*}(name+":{*}readback{*}", getComponent());
 CHARACTERISTIC_COMPONENT_PROPERTY(readback, m_readback_p);
\\
 m_current_p  = new *RWdouble{*}(name+":{*}current{*}", getComponent());
 CHARACTERISTIC_COMPONENT_PROPERTY (current, m_current_p);
\\
 m_status_p = new *ROpattern{*}(name+":{*}status{*}", getComponent());
 CHARACTERISTIC_COMPONENT_PROPERTY(status, m_status_p);
*\}*
\\
Another difference is in the destructor because for each property we must call the destroy method but not the delete. 
\\
*PowerSupply{*}::~{*}PowerSupply{*}() \{
 ...
 (m_readback_p) \{ m_readback_p->destroy(); m_readback_p = 0; \}
 (m_current_p) \{ m_current_p->destroy(); m_current_p = 0; \}
 if (m_status_p) \{ m_status_p->destroy(); m_status_p = 0; \}
\}The rest of the code remains the same apart for the renaming of the variables.
\\
\\
\\
\\

1. Anchor
   _Toc103678591 _Toc103678591

   The ContainerServices

As we saw writing the constructor of the component, it receives a pointer to a maci::ContainerServices object. Really, maci::ContainerServices is an interface and the component receives an implementation of that interface defined in the maci module. The developer is free to replace this default implementation with another one that better fits its needs.
Throw the ContainerServices object the Containers offers the component a set of services freeing the developer of the details of their implementation.
The getContainerServices() method returns a pointer to the container services object so there is no need to store the container services object received in the constructor in a local variable.
Here I report a brief description of the services of the default implementation of the ContainerServices in the maci module. For further details, have a look at the doxygen documentation.
ACE_CString getName() // Return the name of the component
PortableServer::POA_var getPOA() // Return a reference to the POA
// Get a Component of type T
template<class T> T* getComponent(const char *name)
// Get a dynamic component of typoe T
template<class T> T* getDynamicComponent(maci::ComponentSpec
compSpec, bool markAsDefault);
// Get the default component (of type T) that implements the idl interface
template<class T> T* getDefaultComponent(const char* idlType);
// get the descriptor of a component
maci::ComponentInfo getComponentDescriptor(const char* componentName)
// Find components using their name or their type
ACE_CString_Vector findComponents(const char *nameWilcard, const char *typeWildcard)
void releaseComponent(const char *name) // release the component with the given name
void releaseAllComponents() // Release all the components
CDB::DAL_ptr getCDB() // Return a reference to DAL that allows accessing the CDB
PortableServer::POA_var getOffShootPOA() // Return the offShoot POA
// Activate a CORBA servant that implements the offshoot interface
ACS::OffShoot_ptr activateOffShoot(PortableServer::Servant cbServant)
// Deactivate a CORBA offShoot servant
void deactivateOffShoot(PortableServer::Servant cbServant)

1. Anchor
   _Toc519412792 _Toc519412792

   Anchor
   _Toc103678592 _Toc103678592

   Logging and debugging

ACS_TRACE("::PowerSupply::~PowerSupply");
\\
ACS_DEBUG("::PowerSupply::~PowerSupply", "COB destroyed");
\\
ACS_LOG(LM_RUNTIME_CONTEXT, "PowerSupply/DLLOpen", 
       (LM_ERROR, "Failed to create Component - constructor returned 0!"));
Find out more about this in Logging and Archiving (\[R04\]). 

1. Anchor
   _Toc519412795 _Toc519412795

   Anchor
   _Toc103678593 _Toc103678593

   Compiling

To compile, please use the acsMakefile and the ALMA directory structure. All files should be in subdirectories of <xxxx>/ws/ or <xxxx>/, where <xxxx> represents the name of module. If you have made it this far, you should have these files (although the names should be different...):
<xxxx>/idl/acsexmplPowerSupply.idl
<xxxx>/src/acsexmplPowerSupplyImpl.cpp
<xxxx>/include/acsexmplPowerSupplyImpl.h
<xxxx>/config/CDB/schemas/PowerSupply.xsd
<xxxx>/test/CDB/MACI/Components/Components.xml
<xxxx>/test/CDB/alma/TEST_PS_1/TEST_PS_1.xml
Next, create a Makefile (or preferably just change the existing one). It should be located in: <xxxx>/src/Makefile
Since the acsMakefile is rather large and most targets will not be modified, I am going to write only the parts where something has to be written/changed.
Name of main header file – the one, which is described in this document:
#

...