HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Member Functions | Related Functions
rwsf::NamedObject Class Reference

A handle to a named object implementation. A named object is loaded at service startup and is then available to any services in a context. More...

#include <rwsf/core/NamedObject.h>

Inheritance diagram for rwsf::NamedObject:
rwsf::HandleBase

Public Member Functions

 NamedObject ()
 
 NamedObject (const NamedObject &obj)
 
 ~NamedObject ()
 
rwsf::Config getInitParams ()
 
void init ()
 
NamedObjectoperator= (const NamedObject &obj)
 
void setInitParams (const rwsf::Config &initParams)
 
- Public Member Functions inherited from rwsf::HandleBase
bool isValid (void) const
 
bool operator!= (const HandleBase &second) const
 
bool operator== (const HandleBase &second) const
 

Related Functions

(Note that these are not member functions.)

template<class T >
void naming_extract (const NamedObject &attr, T *&value)
 
template<class T >
void operator<< (NamedObject &attr, const T &value)
 
template<class T >
void operator>> (const NamedObject &attr, T &value)
 

Additional Inherited Members

- Protected Member Functions inherited from rwsf::HandleBase
 HandleBase (void)
 
 HandleBase (StaticCtor)
 
 HandleBase (BodyBase *body)
 
 HandleBase (const HandleBase &second)
 
virtual ~HandleBase (void)
 
BodyBase & body (void) const
 
HandleBaseoperator= (const HandleBase &second)
 

Detailed Description

Any object may be loaded at program start, where it is available to services as needed, using named object functionality.

Named objects are also used internally; for instance, transports and message handlers are stored in rwsf::NamedObject instances. In addition, almost any object can be stored in a named object in order to make it available to a service at runtime.

All named objects for a project are defined and configured in a generated configuration file (client-objects.xml for clients and <servicename>_objects.xml for servers). This file exists for each project and defines a "name" and initialization parameters for each named object, hence the term "named object." Once an object has been defined in the relevant configuration file, it is instantiated at runtime and is available by name throughout the service implementation. A global object configuration file can also be specified and loaded separately.

Creating and loading a named object:

  1. Configure the named object to be either local to a service, global, or both:

    • Local: Add the definition of a named object to the service's generated objects configuration file. (See Step 2 below). The code-generated service object configuration file is parsed when a context is loaded; the code-generated client object configuration file is parsed when a client is executed.
    • Global: Reference a named object configuration in the Agent's main configuration file (rwagent.xml by default), specifically within its preStartup and postShutdown methods sections, so that the referenced named objects are loaded at startup. (No objects are loaded by default.)

      <rwsf:methods>
      <rwsf:preStartup>
      <!-- Add this element to load named objects from ${RWSF_CONF}/objects.xml -->
      <rwsf:method name="load-named-objects"
      class="rwsf_agent_methods190.createNamedObjectLoader">
      <rwsf:property name="rwsf:objects-file" value="${RWSF_CONF}/objects.xml"/>
      </rwsf:method>
      </rwsf:preStartup>
      <rwsf:postShutdown>
      <!-- Add this element to make sure the objects have their destructors run on program exit -->
      <rwsf:method name="destroy-named-objects" class="rwsf_agent_methods190.createNamedObjectCleanup"/>
      </rwsf:postShutdown>
      </rwsf:methods>

      Add the method element to the preStartup element in rwagent.xml as shown above. The name of the method can be anything, but must be unique. The property on the startup method must be named rwsf:objects-file.The value of this property should be set to the named objects configuration file you wish to load.

      At Agent startup, this file is loaded and parsed. All named objects specified in this file are created and stored on the global instance of rwsf::NamingContext.You can retrieve named objects using the lookup() method on rwsf::NamingContext.

      To destroy all loaded objects at program exit, define the second method in the postShutdown section. This ensures that the destructors are run for cleanup tasks; otherwise, the program may exit without destroying the global named objects. This method must appear exactly as in the above example and requires no special properties.

  2. Define the named object in the relevant object configuration file, whether local, global, or both.

    • For locally configured named objects, add a new named object definition to the service's generated objects configuration file for either client or server.
    • For globally configured named objects, add the definition to the file referenced in the rwsf:objects-file property for of the object's loading method ("${RWSF_CONF}/objects.xml" in the example above).

    Here is an example of a new NamedObject definition:

    <objects>
    <naming-obj>
    <naming-name>LookupName</naming-name>
    <naming-class>libraryName.createClassName</naming-class>
    <init-param>
    <param-name>SpecificParameterName</param-name>
    <param-value>SpecificParameterValue</param-value>
    </init-param>
    </naming-obj>
    </objects>
    • At the root is an objects element.
    • Add a naming-obj element for each object you wish to define. This includes:
      • The naming-name is the name used to look up the object. Required.
      • The naming-class declares the libraryName.createClassName directive used to load the library and instantiate the object (See the Web Service Development Guide for more information). Required.
      • The init-param element can appear 0-N times, each declaring a new initialization parameter with the given param-name as its name and the given param-value as its value. Optional.

  3. Add an extern "C" function to the specified library (libraryName in this example). The NamingContext, when parsing the above file, tries to call the listed function (createClassName() in this case). This function must have this signature:

    NamedObjectImp* createClassName(void);

    This function must create the object you wish to store and wrap it in NamedObjectImp body. The easiest way to do this is to use a PointerNamedObjectImp templatized on your class type. For example:

    extern "C" {
    NamedObjectImp* createClassName() {
    }
    }

    This, of course, requires that the object is constructable using the default constructor. If you need to create your object first, use the PointerNamedObjectImp constructor that takes the T* parameter, i.e. rwsf::PointerNamedObjectImp::PointerNamedObjectImp(T*,bool), and pass either true or false to the needsDeletion parameter, depending on how you wish to control the lifetime of the object.

  4. Add a function to your class with the following signature, used for object initialization:

    void init(const rwsf::Config& initParams);

    The rwsf::Config object contains all the init-params specified for the object with the param-name mapped to the param-value entries. You can add any initialization parameters required by your object. Failure to include this function will result in errors when compiling or linking your create method due to template errors.

  5. Your object is now available via the global NamingContext from anywhere in your code. Use the naming_extract() global function to access it after the lookup(), like so:

    ClassName* myClass;
    rwsf::naming_extract(obj, myClass);
Note
rwsf::NamedObject itself is a handle to a rwsf::NamedObjectImp body, so a copy of a NamedObject just creates a new handle to the same data.

Constructor & Destructor Documentation

rwsf::NamedObject::NamedObject ( )

Constructs an invalid handle where isValid() returns false.

rwsf::NamedObject::NamedObject ( const NamedObject obj)

Copies a NamedObject handle. Does not copy the data.

rwsf::NamedObject::~NamedObject ( )

Destructor. If this is the last handle pointing to the data, the data is also destroyed.

Member Function Documentation

rwsf::Config rwsf::NamedObject::getInitParams ( )

Returns the initialization parameters for this named object.

void rwsf::NamedObject::init ( )

Initializes the object. For PointerNamedObjectImp object types, this calls init() on the dereferenced object (see class description).

NamedObject& rwsf::NamedObject::operator= ( const NamedObject obj)

Assigns a NamedObject handle. Does not copy the data.

void rwsf::NamedObject::setInitParams ( const rwsf::Config initParams)

Defines initialization parameters for this named object.

Friends And Related Function Documentation

template<class T >
void naming_extract ( const NamedObject attr,
T *&  value 
)
related

Serializes a PointerNamedObjectImp to an argument value of type T*. The provided NamedObject attr must be a handle to a PointerNamedObjectImp.

Exceptions
rwsf::BadCastExceptionThe body is not a PointerNamedObjectImp.
template<class T >
void operator<< ( NamedObject attr,
const T &  value 
)
related

Serializes the provided value of type T into a TypedNamedObjectImp and then sets it as the body of the NamedObject handle attr. If attr already pointed to a body, that reference is lost (and deleted if the last reference), but will not be overwritten.

template<class T >
void operator>> ( const NamedObject attr,
T &  value 
)
related

Serializes a TypedNamedObjectImp to an argument value of type T. The provided NamedObject attr must be a handle to a TypedNamedObjectImp.

Exceptions
rwsf::BadCastExceptionThe body is not a TypedNamedObjectImp.

Copyright © 2019 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is registered trademark of Rogue Wave Software, Inc. in the United States and other countries, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.