Creating and Using Custom Objects

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

16.3 Creating and Using Custom Objects

This section presents a very simple example of how to include a named object in a service. It uses the DayOfWeek example as a basis. Below are the four steps described in this example. They are the same basic steps needed for the creation and use of any named object.

Create some code for a simple string object.
Create an entry point into the code by defining a create() method.
The dayofweek_objects.xml file is expanded to define this object.
The DayOfWeek service code obtains and returns the string object.

16.3.1 Creating the String Object

You first need to create the object that will be loaded into the Agent. Here is the code that creates a string object.

#include <rwsf/core/NamedObject.h>
#include <rwsf/core/Config.h>
#include <rwsf/core/CString.h>

class MyString {
  public:
    MyString() {}
    MyString(const std::string& str) : str_(str) {}
    
    std::string getStr() const {
      return str_;
    }

    void init(const rwsf::Config& initParams) {
      str_ = initParams.getInitParameter("aString");
    }

  private:
    std::string str_;
};

The init() method is required to be in the class that serves as the entry point to your code because the Agent calls this method at startup, passing an rwsf::Config object containing any initialization parameters obtained from the objects.xml file. See Section 16.3.3 below.

16.3.2 Creating an Entry Point to the Object

For the HydraExpress Agent to load an object, the shared library that contains the object must have a well-defined entry point in the form of a create() method.

extern "C" {
  RWSF_CORE_EXPORT rwsf::NamedObjectImp* createMyString() {
     return new rwsf::PointerNamedObjectImp<MyString>(new MyString(),true);
  }
}

At a minimum, the above method and the MyString class must be compiled into a shared library, and the HydraExpress Agent must be able to locate this shared library at startup. To learn more about the support for named objects, see class rwsf::NamedObject in the HydraExpress C++ API Reference Guide.

16.3.3 Configuring the Named Object

The string object is configured in the objects.xml file. The configuration can contain any number of initialization parameters.

<?xml version="1.0" encoding="UTF-8"?>
<objects>
  ...
  <naming-obj>
    <naming-name>MyString</naming-name>                  1
    <naming-class>string.createMyString</naming-class>   2
  </naming-obj>
  <init-param>
    <param-name>aString</param-name>                     3
    <param-value>It might be Wednesday</param-value>     4
  </init-param>
  ...
</objects>

`//1`	Labels the object so the service can locate it.
`//2`	Names the shared library (`string`) and create method (`createMyString`) to be used to instantiate the object.
`//3`	Defines a parameter called `aString`.
`//4`	Defines a value for the parameter.

At HydraExpress Agent startup, the initialization parameters defined for the named object are placed into an rwsf::Config object, which is passed to the init() method for the named object.

16.3.4 Using the Named Object

If you have done everything as described in the previous sections, an object named MyString should be registered in the HydraExpress Agent global naming context. Here is how you would use it in your server implementation code:

std::string DayOfWeekPortTypeImp::getDayOfWeek(rwsf::CallInfo& callInfo,
    const std::string& date_in)
{
  rwsf::NamingContext* c = 
                     rwsf::NamingContext::getGlobalInstance();    //1
  rwsf::NamedObject obj = c->lookup("MyString");                  //2
  MyString *str;                                                  //3
  rwsf::naming_extract<MyString>(obj,str);                        //4
  return std::string(str->getStr());                              //5
}

`//1`	Gets an instance of the global naming context.
`//2`	Looks up the object `MyString` in the global context.
`//3`	Creates an instance of MyString.
`//4`	Calls the global template function `rwrwsf::naming_extract<>()` to serialize the named object value to the MyString type.
`//5`	Returns the string "It might be Wednesday" to the client for the DayOfWeek example. The response, of course, no longer has any relationship to the input date value.

For descriptions of the classes rwsf::NamingContext and rwsf::NamedObject, see the HydraExpress C++ API Reference Guide.

16.3.4.1 Summary

The basic steps to creating and using a named object are:

Identify the object you want to use, coding it if necessary.
Create an entry point -- a create() method -- in the shared library that contains the object.
Configure the named object in objects.xml.
Obtain and use the object in your implementation code.

By analogy with the process described above, you should be able create a named object for any useful code available to you.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.