Home

	Expand Search

e-Adapter Development Kit Programmer's Reference

Chapter 2 New Era of Networks Infrastructure

Chapter 2

New Era of Networks Infrastructure

The e-Adapter Development Kit uses the New Era of Networks Infrastructure as a framework to allow portability. The New Era of Networks Infrastructure provides a wrapper around the Standard Template Library (STL), namespaces, and streams. The resulting code is portable and platform-independent. Adapter developers must understand its applicability to the code they write. Parts of the New Era of Networks infrastructure are discussed in the following sections:

Managing the Standard Template Library

Versions of the STL on different compilers can require different methods for instantiating types. The New Era of Networks Infrastructure provides abstractions for instantiating types correctly and provides wrapper functions for portions of the STL implementation.

Use the following guidelines to determine the vendor and version of the C++ STL to compile against. The version of the STL that is supported natively by the compiler is used on that platform and compiler combination. The platforms currently include Windows NT and 2000 with Visual C++ 6.0, HP-UX with the aCC compiler, Solaris with the Sun WorkShop 6.1, and AIX with the Visual Age 5.0 compiler.

The New Era of Networks Infrastructure provides macros for the STL Containers.

The STL_STRING macro is made available to a source module by including any header file from the Infrastructure. Use the Infrastructure's StringProxy class as a template argument in place of STL_STRING to prevent problems with the length of generated template names.

The containers are included in header files from the Infrastructure of the form INFR/STL_CONTAINER.h, where CONTAINER is one of BITSET, DEQUE, HASHMAP, HASHSET, LIST, MAP, PAIR, QUEUE, SET, STACK, or VECTOR.

The macros prefix container names with an appropriate namespace, if needed, and automatically take care of differences between STL container declarations. All containers and functions are in the STD_NAMESPACE, which may or may not be std::, depending on the STL used.

To include and use an STL map to correlate a string to an integer, the following code could be used:

#include <INFR/STL_MAP.h>

typedef STL_MAP(NNSY_NAMESPACE StringProxy, int32_t) 

        OurMapType;

The predicate and allocator are not used in the preceding example. For a different predicate, use the following code:

#include <INFR/STL.MAP.h>

typedef STL_MAP_PRED(

        NNSY_NAMESPACE StringProxy, 

        int32_t,

        STD_NAMESPACE greater<StringProxy>) OurMapType;

Using Namespaces

Many New Era of Networks components are wrapped within a pair of namespaces on compilers that support namespaces. Namespaces partition the global namespace so that classes and functions from one component do not cause a problem with classes and functions with the same name from another component. The outer namespace is NNSY. The inner namespace is the name of the component, for example, INFR for the Infrastructure and NDO for the New Era of Networks Data Object.

The following are the basic rules of namespaces:

• If you are writing a header file for a library, do not open namespaces. Instead of opening a namespace, use a namespace macro such as NNSY_INFR_NAMESPACE wherever you need to use an infrastructure object.

• If you are writing a source module, do not open any Namespaces until all header files are included. Opening namespaces before all header files are included often causes errors in header files.

• If you are writing a header file for an application, namespaces can be opened, but you must then ensure that ambiguities do not occur in other header files that may be included after the current header file. In this case, you might want to have a single header file control the opening of the namespaces and include all other header files in this header file.

• Global operators, for example, streaming operators and equivalence operators, should be placed in the global namespace.

The Infrastructure provides a set of macros for working with namespaces. Each component also provides a set of macros for working with the specific namespaces declared in the component.

Using Macros

INFR provides macros for use with C++ standard streams. Using these macros not only saves time but also ensures consistency. The following table presents the actual C++ calls, the old INFR stream macros, and the newer INFR macros.

See the INFR/Streams.h header for the macro definitions.

Example Library Header Files

Library header files should use names from New Era of Networks components.

#include <INFR/RCPointer.h>

#include <NDO/NNDOObject.h>

class MyClass

{

protected:

  NNSY_INFR_NAMESPACE RCPointer<NNSY_NDO_NAMESPACE

     NNDOObject> m_pNDO;

public:

  NNSY_NAMESPACE e_SF Foo();

};

The following is an example application header file.

MyClass.h:

#include <INFR/RCPointer.h>

//preferred method:

#include <OurAppSymbols.h>

// or, less preferable method

#include <OurAppNamespaces.h>

class MyClass

{

protected:

  RCPointer<NNDOObject> m_pNDO:

public:

  e_SF Foo():

};

OurAppSymbols.h:

//Names that you are interested in can be selectively 

//pulled without opening entire namespaces. This is the

//safer, preferred method.

#include <INFR/RCPointer.h

#include <NDO/NNDOObject.h>

USING_SYMBOL(NNSY::e_SF)

USING_SYMBOL(NNSY::INFR::RCPointer)

USING_SYMBOL(NNSY::NDO::NNDOObject)

//...etc...

OurAppNamespaces.h:

// You can open everything. Make sure the namespaces 

// that you are going to open exist. A header file that // declares the namespaces that you are opening may not

// be included.

BEGIN_NAMESPACE(NNSY)

BEGIN_NAMESPACE(ND0)

BEGIN_NAMESPACE(INFR)

END_NAMESPACE(INFR)

END_NAMESAPCE(NDO)

END_NAMESPACE(NNSY)

// The application guarantees that we do not conflict 

// with any of the names in the New Era of Networks

// namespace or its contained NDO or INFR

/ namespaces. Further, no other component conflicts with

// any of the names.

USING_NAMESPACE(NNSY)

USING_NAMESPACE(NDO)

USING_NAMESPACE(INFR)

Source modules usually look like the following:

#include <MyClass.h>

#include <OtherStuff.h>

USING_NAMESPACE_STD

USING_NAMESPACE(NNSY)

USING_NAMESAPCE(INFR)

USING_NAMESPACE(NDO)

e-SF

MyClass::Foo()

{

   RCPointer<NNDOObject> pTempNDO = m_pNDO;

   m_pNDO = getNDO();    //etc.

   return SF_Success:

}

Using Streams

To allow use of the standard C++ streams for compilers that support them and also allow the use of old streams in compilers that do not support them, the Infrastructure provides a set of typedefs and macros to abstract the stream types. On systems that support both stream types, the standard C++ streams are used by default by New Era of Networks Rules, Formatter, and Messaging.

The stream typedefs are in the New Era of Networks namespace. Stream typedefs must follow the guidelines for using namespaces.

For non-platform independent code, the macros do not need to be used. Either old streams or new streams can be used directly. Macros are important when both old streams and new streams are mixed. This situation occurs frequently with third party libraries that use old streams. In this situation, the two stream types can be mixed if the namespaces are explicitly used for every name.

To use old streams, each name must be prefixed by ::, for example, ::ostream.

To use new streams, std:: must be prefixed to each name, for example, STD_NAMESPACE cout. Using the STD_NAMESPACE macro makes the code portable when the new style of streams are used only on platforms that support them; the old style of streams are used otherwise.

Example of Streams in Library Header Files

The following is an example library header file:

#include <INFR/Streams.h>

class MyClass

{

public:

   virtual void dump(NNSY_NAMESPACE OStream& os) const;

};

inline NNSY_NAMESPACE OStream&

operator << (NNSY_NAMESPACE OStream& os, const MyClass& rhs)

{

   rhs.dump(os);

   return os;

}