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:

Public Member Functions
	NamedObject ()

	NamedObject (const NamedObject &obj)

	~NamedObject ()

rwsf::Config	getInitParams ()

void	init ()

NamedObject &	operator= (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

HandleBase &	operator= (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:

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>
  
  
  
  <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>
  
  
  
  <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.
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.
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() {

return new rwsf::PointerNamedObjectImp<ClassName>;

}

}

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.
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.
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:

rwsf::NamedObject obj = rwsf::NamingContext::getGlobalInstance()->lookup("LookupName");

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
	)

Exceptions

rwsf::BadCastException The body is not a PointerNamedObjectImp.

template<class T >

void operator<<	(	NamedObject &	attr,
		const T &	value
	)

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
	)

Exceptions

rwsf::BadCastException The body is not a TypedNamedObjectImp.

HydraExpress™ C++ API Reference Guide

Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation