# Spectra ORB

# C++ Edition

# Lightweight Naming Service Guide

![in-commerce\nlogistics](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/48c115577b3813ea0966c70410db5f9f24101d80018a0cdc54ebe6730641f992.jpg)

# Spectra ORB

# C++ Edition

# LIGHTWEIGHT

# NAMING SERVICE GUIDE

# Copyright Notice

© 2013 PrismTech Limited. All rights reserved.

This document may be reproduced in whole but not in part.

The information contained in this document is subject to change without notice and is made available in good faith without liability on the part of PrismTech Limited or PrismTech Corporation.

All trademarks acknowledged.

# CONTENTS

# Table of Contents

# Preface

About the Lightweight Naming Service Guide . . . . . . . . . vii

Contacts . . . . . . . viii

# Introduction

Description 3

OMG Standard Features . . . .

# The Spectra ORB Lightweight Naming Service

# Chapter 1 Basic Concepts 7

1.1 OMG Standard Features . . . .

1.1.1 Names . .

1.1.2 Naming Contexts . . .

# Chapter 2 Specific Features 1 1

2.1 Naming Context Creation and Destruction . . . . . . . . 12

2.2 Object Binding and Unbinding Operations . . . . . . . . . 12

2.3 Accessing Objects and Naming Contexts . . . . . . . . 13

# Chapter 3 Using the Service 15

3.1 Running the Service . . . . . . . 15

3.1.1 Embedding the Service . . . . . 15

3.1.1.1 POA Argument Choices . . . . . . 16

3.1.1.2 Configuration Structure . . . . . 16

3.1.1.3 Example Server Module . . . . . 17

3.1.2 Running from the Command Line. . . . . 19

3.1.2.1 Example . . . . . 19

3.1.3 Running on a Fixed Endpoint . . . . . 20

# Chapter 4 Creating Applications 2 1

4.1 A Basic Application . . . . . . . . . 21

4.1.1 Registering Objects . . . . . 22

4.1.1.1 Obtaining the Root Context . . . . . 22

4.1.1.2 Example server source code . . . . . 22

4.1.1.3 Example client source code . . . . 24

# Chapter 5 Supplemental Information 29

5.1 Exceptions . . . . . . . . . 29

# Appendix A Examples’ Source Code 3 3

# Index 37

# P re f a c e

# About the Lightweight Naming Service Guide

The Lightweight Naming Service Guide explains how to use the Spectra ORB Lightweight Naming Service C++ Edition product.

# Intended Audience

The Lightweight Naming Service Guide is intended to be used by developers who wish to integrate the Spectra ORB Lightweight Naming Service into products which comply with OMG standards for object services. Readers should have a good understanding of the relevant programming languages (for example C++, IDL) and of the relevant underlying technologies (for example, CORBA).

# Organisation

The Lightweight Naming Service Guide provides:

• a high level description and list of main features
• explanations of the OMG Naming Service architecture and concepts
• descriptions of how to configure, run and deploy the Spectra ORB Lightweight Naming Service
• descriptions of how to create applications using the Spectra ORB Lightweight Naming Service
• other information about the service

# Conventions

The conventions listed below are used to guide and assist the reader in understanding the Lightweight Naming Service Guide.

<table><tr><td>!</td><td>Item of special significance or where caution needs to be taken.</td></tr><tr><td>i</td><td>Item contains helpful hint or special information.</td></tr><tr><td>WIN</td><td>Information applies to Windows (e.g. XP, Vista, Windows 7) only.</td></tr><tr><td>UNIX</td><td>Information applies to Unix-based systems (e.g. Solaris) only.</td></tr><tr><td>C</td><td>C language specific.</td></tr><tr><td>C++</td><td>C++ language specific.</td></tr><tr><td>Java</td><td>Java language specific.</td></tr><tr><td></td><td>Hypertext links are shown asblue italic underlined.</td></tr></table>

On-Line (PDF) versions of this document: Items shown as cross references to other parts of the document, e.g. Contacts on page viii, behave as hypertext links: users can jump to that section of the document by clicking on the cross reference.

```txt
% Commands or input which the user enters on the command line of their computer terminal
```

Courier, Courier Bold, or Courier Italic fonts indicate programming code and file names.

Extended code fragments are shown in shaded boxes:

```javascript
NameComponent newName[] = new NameComponent[1];
// set id field to "example" and kind field to an empty string scarf
newName[0] = new NameComponent("example", "");
```

Italics and Italic Bold are used to indicate new terms, or emphasise an item.

Arial Bold is used to indicate user related actions, e.g. File > Save from a menu.

Step 1: One of several steps required to complete a task.

# Contacts

PrismTech can be reached at the following contact points for information and technical support.

<table><tr><td>USA Corporate Headquarters</td><td>European Head Office</td></tr><tr><td>PrismTech Corporation</td><td>PrismTech Limited</td></tr><tr><td>400 TradeCenter</td><td>PrismTech House</td></tr><tr><td>Suite 5900</td><td>5th Avenue Business Park</td></tr><tr><td>Woburn, MA</td><td>Gateshead</td></tr><tr><td>01801</td><td>NE11 0NG</td></tr><tr><td>USA</td><td>UK</td></tr></table>

<table><tr><td>Tel: +1 781 569 5819</td><td>Tel: +44 (0)191 497 9900</td></tr><tr><td></td><td>Fax: +44 (0)191 497 9901</td></tr></table>

Web: http://www.prismtech.com

Technical questions: crc@prismtech.com (Customer Response Center)

Sales enquiries: sales@prismtech.com

# INTRODUCTION

# Description

The Spectra ORB Lightweight Naming Service C++ Edition provides a straightforward way of finding and using objects by associating meaningful, human-understandable names to those objects. The Spectra ORB Lightweight Naming Service is used like the white pages of a telephone directory to find an object and obtain its object reference, without the need to resort to complex programming or proprietary ORB mechanisms.

The Spectra ORB Lightweight Naming Service C++ Edition is compliant with the OMG’s Lightweight Naming Service Specification and satisfies the Naming Service requirements of the Software Communications Architecture (SCA).

The OMG’s Lightweight Naming Service Specification is a sub-set of the full OMG specification and is intended to provide a service which has a minimal footprint and uses a minimum of resources. This service is designed for use in restricted deployment environments, such as in embedded systems and in the Software Defined Radio (SDR) domain.

This implementation has been designed and implemented to be as small and as proficient as possible: it is designed for use in highly demanding environments where footprint size and resources are limited.

![The image displays a standard warning sign featuring a red triangular border with a white interior. Centered inside is a black exclamation point.](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/03a4e33cd6eca4256116fda1692ecec4d43443aa8ca05dffbf6126cd34c4d2b9.jpg)

The Spectra ORB Lightweight Naming Service C++ Edition does not support the kind property of the CosNaming::NameComponent. The Service will ignore this property when binding or resolving names. Developers should ensure that they use unique id values creating name components.

# OMG Standard Features

The Spectra ORB Lightweight Naming Service provides the following OMG specified features:

• enable objects to be located by using human-intelligible names by binding names to objects
• add and remove name bindings
• change the object which a name is bound to
• group names in logical hierarchies

# THE SPECTRA ORBLIGHTWEIGHT NAMING

# SERVICE

# CHAPTER

# 1 Basic Concepts

This section describes the basic concepts and architecture of the OMG’s Lightweight Naming Service as defined in the OMG’s Lightweight Services Specification.

i The OMG’s Lightweight Naming Service is a sub-set of the full OMG Naming Service Specification. The Lightweight Specification omits features which are considered not to be essential in a restricted environment. The purpose of this is to reduce footprint size and enable the service to be deployed on memory or storage constrained platforms. The features provided by the Lightweight Naming Service only include those defined as part of the NamingContext interface. The features of this interface are described under Section 2, Specific Features, on page 11.

# 1.1 OMG Standard Features

The Lightweight Naming Service has the ability to:

• give meaningful names to objects (name bindings)
• allow objects, which have been bound to names, to be easily found (resolve)
• organise names in logical hierarchies (naming contexts)

# 1.1.1 Names

The Naming Service associates meaningful names with objects. These names can be used to retrieve or reference the object, or in other words, obtain the object’s IOR. An association between a name and an object is known as a name binding.

A Naming Service name is an object in its own right. A name contains a sequence of one or more name components. A name component has two string-type attributes, id and kind. The id and kind attributes identify the name.

A name contains a sequence of one or more name components. A name with a single name component is called a simple name. A name which contains a sequence of two or more name components is called a compound name. Compound names are used to access name bindings when they are in a hierarchy of naming contexts, described below.

A name binding is held in or otherwise associated with a naming context. A name binding cannot exist outside of a naming context. Names are bound to naming contexts, as well as to objects. It is possible to have orphaned contexts if the name binding is removed without keeping a reference to the context being unbound.

An object can be bound to one or more names, but a name can only be bound to one object. If an object is bound to more than one name, then any of those names can be used to locate the object.

Resolving is the process of locating an object or naming context by using its name.

# 1.1.2 Naming Contexts

A naming context is an object which contains name bindings. Each name in a given naming context must be unique, in other words, the combination of a name’s name component id and kind values must be unique. The name can be used in other naming contexts.

Naming hierarchies can be created by binding a naming context to another naming context. A simple naming context hierarchy is shown in Figure 1. Names in a naming context can refer to other naming contexts as well as to objects. A hierarchy of naming contexts is called a naming graph.

The top level of the naming graph is called the root context. The root context is also the default context, that is, it does not need to be explicitly created whereas all other contexts, child contexts of the root context, must be explicitly created.

Objects, and contexts themselves, are referenced by following the hierarchy of naming contexts, starting from the root context and ending with the desired object or naming context. Technically, the object or context can be referenced in one of two ways:

1. Obtain an object reference to the context which contains the required object or context. The object’s name can then be used to obtain the object’s IOR.
2. Construct a compound name which contains a sequence of name components, where each name component identifies each successive naming context in the naming graph and where the last name component identifies the required object or context.

![The flowchart depicts a hierarchical naming structure involving 'Naming Context' blocks (rectangles) and 'CORBA object' blocks (green circles).\n\n**Labeled Blocks:**\n*   **Root Naming Context**: Lists 'name 1', 'name 2', 'name 3', '.', 'name n'.\n*   **CORBA object B**\n*   **CORBA object A**\n*   **CORBA object D**\n*   **Naming Context 2**: Lists 'name 1', 'name 2', 'name 3', '.', 'name n'.\n*   **Naming Context 4**: Lists 'name 1', 'name 2', 'name 3', '.', 'name n'.\n*   **Naming Context 3**: Lists 'name 1', 'name 2', 'name 3', '.', 'name n'.\n*   **CORBA object C**\n*   **CORBA object E**\n\n**Connections:**\n*   **Root Naming Context** connects to **CORBA object B**, **CORBA object A**, **Naming Context 2**, and **CORBA object D**.\n*   **Naming Context 2** connects to **Naming Context 4** and **Naming Context 3**.\n*   **Naming Context 4** connects to **CORBA object C** and **CORBA object E**.\n*   **Naming Context 3** connects to **CORBA object E**.](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/da0adb98062ea78c42d971e601c389a25b403a8bd279bd352a4849f6ad9e9f66.jpg)

Figure 1 Example Naming Graph

For example, in Figure 1 objects A, B and NamingContext2 are bound directly to the root context: they can be referenced using a simple name (containing the name component which identifies the objects themselves). Objects C and E are bound to child contexts lower down the hierarchy: in order to access objects C and E from the root context, the name component for each successive naming context must be provided as a compound name. For example, the compound name for referencing object C from the root context will contain a sequence which looks like this in pseudo-code:

```txt
name[0] = NamingContext2.nameComponent
name[1] = NamingContext4.nameComponent
name[2] = C.nameComponent
```

The root context is always implicit in a compound name; a special operation, resolve\_initial\_references, is performed once to obtain the root context, and all subsequent resolve operations depend on that.

# CHAPTER

# 2 Specific Features

The Spectra ORB Lightweight Naming Service’s features are described below. As mentioned previously, the service conforms to the OMG’s Lightweight Services Specification and is a subset of the full OMG Naming Service Specification.

The Spectra ORB Lightweight Naming Service supports a subset of the NamingContext interface.

The interfaces, datatypes, methods and exceptions supported by the Spectra ORB Lightweight Naming Service are listed below.

# Interfaces and Datatypes

• Name (datatype)
• NameComponent (datatype)
• NamingContext (interface)

# NamingContext Methods

• bind()
• rebind()
• resolve()
• unbind()
• bind\_new\_context()
• destroy()

# NamingContext Exceptions

• NotFoundReason
• NotFound
• CannotProceed
• InvalidName
• AlreadyBound
• NotEmpty

i The BindingIterator or NamingContextExt interfaces are not supported by the Lightweight Naming Service.

# 2.1 Naming Context Creation and Destruction

The NamingContext interface provides a NamingContext creation operation and a destroy operation, defined in IDL as:

```c
NamingContext bind_new_context (in Name n)
    raises (NotFound, CannotProceed, InvalidName, AlreadyBound);

void destroy () raises (notEmpty);
```

The bind\_new\_context operation creates a new Naming Context and binds it using the supplied name.

The destroy operation requests the destruction of a NamingContext object. The naming context must be empty. After destroy is invoked, no further operations can be invoked on the object reference of the naming context object.

![A red triangular warning sign with a white interior featuring a large black exclamation mark in the center.](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/ee4bb1bf20bee6da4b6f3985fc1abe3d55705abdbd8cccb649c78721d08e7cd3.jpg)

Bindings to a destroyed context are not removed. To do so would require a context to know about all of its parents as well as its children. An attempt to resolve a binding to a destroyed context will throw the CORBA.INV\_OBJREF exception. Accordingly, bindings to a naming context should be removed before it is destroyed.

When a hierarchical name is used to create a new context, all the contexts that constitute the path to the new context must already exist or the NotFound exception will be raised

# 2.2 Object Binding and Unbinding Operations

The NamingContext interface provides the following object binding and unbinding operations, defined in IDL as:

```c
void bind (in Name n, in Object obj)
    raises (NotFound, CannotProceed, InvalidName, AlreadyBound);

void rebind (in Name n, in Object obj)
    raises (NotFound, CannotProceed, InvalidName);

void unbind (in Name n)
    raises (NotFound, CannotProceed, InvalidName);
```

The bind operations allow binding to occur between a name and either a generic CORBA object or a Naming Context. In order to bind a CORBA object, the name to bind against must be correctly constructed. Given a name with n components, the first n - 1 components must resolve to a bound NamingContext.

The rebind operation is identical to the bind operation except that the AlreadyBound exception is not thrown; an existing binding with the same name is replaced by the new binding.

# 2.3 Accessing Objects and Naming Contexts

The resolve operation is used to obtain the object references of naming contexts and named objects, defined in IDL as:

```txt
Object resolve (in Name n) raises (NotFound, CannotProceed, InvalidName);
```

The resolve operation takes a name and returns the object, if any, bound to that name.

# CHAPTER

# 3 Using the Service

This section describes the specific procedures and requirements for creating and running CORBA-based applications with the Spectra ORB Lightweight Naming Service C++ Edition. (Please note that this section is not intended as a tutorial of how to write CORBA-based applications with the Naming Service.)

# 3.1 Running the Service

The Naming Service instances can be run from the command line or by embedding into application or module code. Instructions for running the service using these methods is described in the following sections, Embedding the Service, below, and Running from the Command Line on page 19.

# 3.1.1 Embedding the Service

![The image displays a red triangular warning sign with a thick red border and a white interior. Centered inside the triangle is a black exclamation point (!), and directly below it is a small black diamond (♦).](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/7b9c7ee8032c82fa85d776663afa32d842d153071962c1571e7e2684d6c5b0e2.jpg)

Refer to the Platforms section of the User Guide for specific compiler and linking details for your platform.

The following basic tasks must be performed in order to embed a Naming Service into an executable or code module:

Step 1: Include the following #include statements in your code:

```c
#include "CosNaming.h"
#include "eOrb/EORB/NamingService.h"
```

![The image displays a vertical strip containing a single lowercase blue letter 'i'.](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/9206b25522dd106eac64a6fcc29b91c23e789a4f3d6505a7f762281ed39cd6c2.jpg)

Ensure your build system has \$(EORBHOME)/include/eOrb/services/lw on its include path.

Step 2: When compiling and linking instruct the linker to link the e\_lwnaming\_s.lib library file.

Step 3: Configure the service instance by setting the property fields in the naming service’s configuration structure: these properties are used to determine specific aspects of your instance’s behaviour and are described later.

Step 4: Initialise a Naming Service instance by using the Naming Service’s init() method:

root\_ctx = EORB::NamingService::init(orb, poa, config) where:

orb is the orb which the service is to be run on

poa is the POA which the service is to run in (see POA Argument Choices below)

config is the service instance’s configuration (see Configuration Structure below)

# 3.1.1.1 POA Argument Choices

The poa agrument allows the user to create their own poa for the Naming Service that has properties configured to meet the demands of their system or implementation.

There are two choices for the poa argument: NULL or User Defined POA

# 1. NULL

In this case the EORB::NamingService will create a POA where:

id assignment policy is set to PortableServer::USER\_ID id\_uniqueness\_policy is set to PortableServer::MULTIPLE\_ID

lifespan\_policy is set to PortableServer::PERSISTENT if the config option qosPersistent is set to TRUE, otherwise it will be set to PortableServe::TRANSIENT

# 2. User Defined POA

The User Defined POA MUST have the following policies set:

id assignment policy set to PortableServer::USER\_ID id\_uniqueness\_policy set to PortableServer::MULTIPLE\_ID

The config option qosPersistent will be ignored when a user defined POA is provided. If persistence is required, then the appropriate policies must be set on the user defined POA.

All other policies can be set as needed.

# 3.1.1.2 Configuration Structure

The structure mentioned in Step 3: above defines the property fields described below in Table 1, Configuration Property Descriptions. An example of setting the configuration structure fields is shown in Example 1, Setting the Configuration Structure Fields, on page 17.

Table 1 Configuration Property Descriptions

<table><tr><td>Property</td><td>Description</td></tr><tr><td>qosContextLocking</td><td>Controls the read and write locking protection for concurrent access to naming contexts. qosContextLocking should normally only be set to false, unlocked, when the service is used in read-only mode.The default is true, locked.</td></tr><tr><td>qosMaxContexts</td><td>The number of naming contexts that this service instance is expected to create.The default value is 1024.</td></tr><tr><td>qosPersistent</td><td>Creates a persistent IOR for the Naming Service and causes it to listen on a fixed port. This enables the Naming Service to always be resolved using the same IOR or CORBALOC, even when the service has been shutdown and restarted.</td></tr></table>

# Example 1 Setting the Configuration Structure Fields

```txt
EORB::NamingService::Config config;
config.qosMaxContexts = 500;
```

# 3.1.1.3 Example Server Module

The following example code shows how a Naming Service instance can be created with the default Naming Service POA.

```cpp
#include "eorb_name_i.h"
#include "eOrb/EORB/NamingService.h"

EORB_MAIN (server)
{
    EORB_DECLARE_ENV;

    eorb_name_impl * servant = 0;
    EORB::NamingService::Config config;
    config.qosMaxContexts = 11;
    config.qosPersistent = 0;

    EORB::Plugin::Current::add ();
    EORB::Plugin::IIOP::add ();
    EORB::Plugin::POA::addrows ;

    EORB_Stdio_plugin ();
    EORB_File_pluginrows ;

    EORB_TRY
    {
    printf("Naming server starting\n");
    }
}
```

```txt
// Naming Service setup
CosNaming::NamingContext_var ctx;
PortableServer::POA_var poa;
PortableServer::POA_var child_poa;
PortableServer::ObjectId_var oid;
CORBA::Object_var obj;
CORBA::ORB_var orb;

orb = CORBA::ORB_init (argc, argv EORB_ENV_VARN);
EORB_CHECK_ENV;

// Get the RootPOA

obj = orb->resolve_initial_references ("RootPOA" EORB_ENV_VARN);
EORB_CHECK_ENV;

poa = PortableServer::POA::_narrow (obj EORB_ENV_VARN);
EORB_CHECK_ENV;

// Create servant and activate it

servant = new eorb_name_impl (orb EORB_ENV_VARN);
EORB_CHECK_ENV;

oid = poa->activate_object (servant EORB_ENV_VARN);
EORB_CHECK_ENV;

EORBTest::name_var server = servant->_this (EORB_ENV_VAR1);
EORB_CHECK_ENV;

// Initialise a naming service

ctx = EORB::NamingService::init (
    orb,
    NULL,
    config
    EORB_ENV_VARN
);
EORB_CHECK_ENV;

orb->register_initial_reference ("NameService", ctx EORB_ENV_VARN);
EORB_CHECK_ENV;

orb->register_initial_reference ("server", server EORB_ENV_VARN);
EORB_CHECK_ENV;

printf ("Name Service started...\n");

orb->run (EORB_ENV_VAR1);
EORB_CHECK_ENV;

orb->destroy (EORB_ENV_VAR1);
EORB_CHECK_ENV;
}
EORB_CATCH (CORBA::Exception, exc)
```

```awk
{
    printf ("Exception %s\n", exc._rep_id ());
}
EORB_END_TRY
delete servant;
printf ("Naming server complete\n");
return 0;
}
```

# 3.1.2 Running from the Command Line

An alternative to writing a module which creates and runs a Naming Service server is to run the Spectra ORB Lightweight Naming Service executable, lwnamingcpp, f r o m t h e c o m m a n d l i n e . l w n a m i n g c p p i s l o c a t e d i n t h e \$EORBHOME/bin/\$EORBENV directory. The lwnamingcpp executable can be run with zero or more of the command line options listed below in Table 2.

Table 2 Command Line Options

<table><tr><td>Option</td><td>Description</td></tr><tr><td>-NameServiceContextLocking&lt;on|off&gt;</td><td>Sets context locking state (see above)The default is on.</td></tr><tr><td>-NameServiceMaxContexts &lt;num&gt;</td><td>Sets the expected number of contexts to be created, The default is 100.</td></tr><tr><td>-NameServicePersistent &lt;yes|no&gt;</td><td>Sets whether the lifespan policy is set to PortableServer::PERSISTENT or PortableServer::TRANSIENTThe default is yes (= PERSISTENT).</td></tr><tr><td>-NameServiceUIOP</td><td>Runs the service on a UIOP endpoint. Only available on systems where UIOP is a supported transport.The default is no.</td></tr></table>

# 3.1.2.1 Example

The following command line example demonstrates how to start a Naming Service instance, on a UNIX operating system, where:

• the expected number of contexts to be created is 100

```batch
% lwnamingcpp -NameServiceMaxContexts 100
```

# 3.1.3 Running on a Fixed Endpoint

The server can be run on a fixed endpoint by running with the -ORBPOAEndpoints argument. The Name Service servant is created within a child POA NameService so for example can be run on a fixed IIOP endpoint with:

-ORBPOAEndpoints NameService:iiop:&lt;host&gt;:&lt;port&gt;

and resolved as an initial reference by a client using:

-ORBInitRef NameService=corbaloc:iiop:&lt;host&gt;:&lt;port&gt;/NameService

# CHAPTER

# Creating Applications

This section describes how to create client-server applications which use the Spectra ORB Lightweight Naming Service. Topics covered include:

• clients and servers that use the Naming Service for object resolution
• creating and destroying naming contexts
• associating objects with name bindings and adding them to naming contexts
• resolving objects by using name bindings.

A This release of the Spectra ORB Lightweight Naming Service C++ Edition does not support the kind property of the CosNaming::NameComponent. Although the examples shown here use the kind property, it is nonetheless ignored by the Service when binding or resolving names.

# i Note

• For the sake of clarity and brevity, the examples shown here do not have all of the error or exception trapping code normally used. Exceptions and errors must, naturally, be caught and properly handled in a production system.
• Applications which use the Spectra ORB Lightweight Naming Service must

\- have a #include "CosNaming.h" line in the source code file

\- link the e\_lwnaming\_cpp.lib library file

• Applications or modules which create and run Spectra ORB Lightweight Naming Service instances must also:

- have a #include “eOrb/ORB/NamingService.h” line in the source code file
- be implemented and configured as described in Section 3, Using the Service.

# 4.1 A Basic Application

A basic client-server application which uses the Spectra ORB Lightweight Naming Service must:

• enable its server and client components to obtain an object reference to a running Spectra ORB Lightweight Naming Service server instance (referred to here as the naming service for brevity)
• register objects with the naming service

• retrieve or resolve the object registered with the naming service

An example application demonstrates how these tasks can be performed. The application:

• has a server which
- creates and activates a Spectra ORB Lightweight Naming Service servant

• has a client which

- obtains a reference to the servant
- creates and binds contexts and objects with the naming service
- retrieves bindings using list and iterator methods
- unbinds objects and contexts
- destroys contexts

The complete source code for the example application is provided as source files in examples/cpp/services/naming/lw below the installation directory.

# 4.1.1 Registering Objects

The server must make its objects available to clients, in other words, it must provide some mechanism which enables its clients to resolve its objects. It can do this using various methods, such as saving the objects’ IORs to a file or by using the naming service (see the Spectra ORB’s User Guide for other alternatives): the example server uses the naming service.

# 4.1.1.1 Obtaining the Root Context

The first task which the server must do, aside from creating the objects which clients will use, is to obtain the root context of a naming service.

The root context is a normal CORBA object and can be obtained using the standard CORBA methods for object resolution. For this example, a separate module can create a naming service instance and publish its stringified IOR in a file called NamingService.ior. 1 The server can use this naming service by retrieving its stringified IOR and converting it to an object reference.

The following example server code initialises the ORB then creates and activates a servant.

# 4.1.1.2 Example server source code

The complete source code for the supplied example server is shown below:

```c
#include "eOrb/EORB/Plugin/Current.h"
```

1. An example module which creates a Naming Service server is shown under Example Server Module on page 17.

```cpp
#include "eorb_name_i.h"
#include "eOrb/EORB/NamingService.h"

EORB_MAIN (server)
{
    EORB_DECLARE_ENV;

    eorb_name_impl * servant = 0;
    EORB::NamingService::Config config;
    config.qosMaxContexts = 11;
    config.qosPersistent = 0;

    EORB::Plugin::Current::add ();
    EORB::Plugin::IIOP::add ();
    EORB::Plugin::POA::addrows */

    EORB_Stdio_plugin ();
    EORB_File_plugin();

    EORB_TRY
    {
    printf ("Naming server starting\n");

    // Naming Service setup

    CosNaming::NamingContext_var ctx;
    PortableServer::POA_var poa;
    PortableServer::POA_var child_poa;
    PortableServer::ObjectId_var oid;
    CORBA::Object_var obj;
    CORBA::ORB_var orb;

    orb = CORBA::ORB_init (argc, argv EORB_ENV_VARN);
    EORB_CHECK_ENV;

    // Get the RootPOA

    obj = orb->resolve_initial_references ("RootPOA" EORB_ENV_VARN);
    EORB_CHECK_ENV;

    poa = PortableServer::POA::_narrow (obj EORB_ENV_VARN);
    EORB_CHECK_ENV;

    // Create servant and activate it

    servant = new eorb_name_impl (orb EORB_ENV_VARN);
    EORB_CHECK_ENV;

    oid = poa->activate_object (servant EORB_ENV_VARN);
    EORB_CHECK_ENV;

    EORBTest::name_var server = servant->_this (EORB_ENV_VAR1);
    EORB_CHECK_ENV;

    // Initialise a naming service

    ctx = EORB::NamingService::init (
    orb,
```

```c
NULL,
config
EORB_ENV_VARN
);
EORB_CHECK_ENV;

orb->register_initial_reference ("NameService", ctx EORB_ENV_VARN);
EORB_CHECK_ENV;

orb->register_initial_reference ("server", server EORB_ENV_VARN);
EORB_CHECK_ENV;

printf ("Name Service started...\n");

orb->run (EORB_ENV_VAR1);
EORB_CHECK_ENV;

orb->destroy (EORB_ENV_VAR1);
EORB_CHECK_ENV;
}
EORB_CATCH (CORBA::Exception, exc)
{
    printf ("Exception %s\n", exc._rep_id());
}
EORB_END_TRY

delete servant;

printf ("Naming server complete\n");

return 0;
}
```

# 4.1.1.3 Example client source code

The complete source code for the supplied example client is shown below:

```cpp
#include "CosNaming.h"
#include "eorb_name.h"

void lightweight_naming_examples
(
    CosNaming::NamingContext_ptr root_ctx
    EORB_ENV_ARGN
)
{
    EORB_TRY
    {
    printf ("Binding 10 names into a naming context");

    CORBA::Object_var obj = new CORBA::Object;
    CosNaming::NamingContext_var ctx;
    CosNaming::NameComponent comp;
    CosNaming::Name name (1);
    name.length (1);
    unsigned long i = 0;
```

```c
/* Bind 10 objects into root context, 5 contexts, 5 objects */
for (i = 0; i &lt; 10; i++)
{
    char idbuf[32] = "";
    if (i &lt; 5)
    {
    sprintf(idbuf, "context binding #%ld", i);
    }
    else
    {
    sprintf(idbuf, "object binding #%ld", i);
    }

    comp.id = (const char*) idbuf;
    name[0] = comp;

    if (i &lt; 5) /* bind context */
    {
    ctx = root_ctx-&gt;bind_new_context(name EORB_ENV_VARN);
    EORB_CHECK_ENV;

    printf("Bind new context to name: %s\n", idbuf);
    }
    else /* bind object */
    {
    root_ctx->bind(name, obj.in()EORB_ENV_VARN);
    EORB_CHECK_ENV;

    printf("Bind object to name: %s\n", idbuf);
    }
}

/* Resolve bindings and unbind objects and contexts, destroy contexts */
for (i = 0; i &lt; 10; i++)
{
    char idbuf[32] = "";
    if (i &lt; 5)
    {
    sprintf(idbuf, "context binding #%ld", i);
    }
    else
    {
    sprintf(idbuf, "object binding #%ld", i);
    }

    comp.id = (const char*) idbuf;
    name[0] = comp;

    obj = root_ctx-&gt;resolve(name EORB_ENV_VARN);
    EORB_CHECK_ENV;

    printf("Resolve binding: %s\n", idbuf);

    root_ctx->unbind(name EORB_ENV_VARN);
    EORB_CHECK_ENV;
```

```cpp
printf (" Unbind from name: %s\n", idbuf);
if (i &lt; 5)
{
    ctx = CosNaming::NamingContext::_narrow (obj.in ()
EORB_ENV_VARN);
    EORB_CHECK_ENV;
    printf (" Narrow object to context");
    ctx-&gt;destroy(EORB_ENV_VAR1);
    EORB_CHECK_ENV;
    printf (" Destroy context");
}
}
EORB_CATCH (CORBA::Exception, exc)
{
    printf ("Exception: %s\n", exc._rep_id());
}
EORB_END_TRY
}

EORB_MAIN (client)
{
    EORB_DECLARE_ENV;

    CORBA::ORB_var orb;
    CORBA::Object_var obj;
    CosNaming::NamingContext_var root;
    EORBTest::name_var example;

    EORB::Plugin::IIOP::add();

    EORB_TRY
{
    printf ("Naming LW client starting\n");

    orb = CORBA::ORB_init (argc, argv EORB_ENV_VARN);
    EORB_CHECK_ENV;

    obj = orb->resolve_initial_references ("NameService"
EORB_ENV_VARN);
    EORB_CHECK_ENV;
    root = CosNaming::NamingContext::_narrow (obj EORB_ENV_VARN);
    EORB_CHECK_ENV;

    obj = orb->resolve_initial_references ("server" EORB_ENV_VARN);
    EORB_CHECK_ENV;
    example = EORBTest::name::_narrow (obj EORB_ENV_VARN);
    EORB_CHECK_ENV;

    lightweight_naming_examples (root EORB_ENV_VARN);
    EORB_CHECK_ENV;

    root->destroy (EORB_ENV_VAR1);
    EORB_CHECK_ENV;
```

```cpp
example->shutdown (EORB_ENV_VAR1);
EORB_CHECK_ENV;

orb->destroy (EORB_ENV_VAR1);
EORB_CHECK_ENV;
}
EORB_CATCH (CORBA::Exception, exc)
{
    printf ("Exception: %s\n", exc._rep_id());
}
EORB_END_TRY

printf ("Naming LW client complete\n");
return 0;
}
```

The example client first obtains the root context of the naming service, resolves the initial reference to the example server, and binds in five new contexts and five objects. It then resolves the bindings and unbinds and destroys them.

# CHAPTER

# Supplemental Information

# 5.1 Exceptions

The exceptions raised by the Spectra ORB Lightweight Naming Service are listed in Table 3.

Table 3 Spectra ORB Lightweight Naming Service Exceptions

<table><tr><td>Name</td><td>Purpose</td></tr><tr><td>AlreadyBound</td><td>Indicates an object is already bound to the specified name. Only one object can be bound to a particular name in a context.</td></tr><tr><td>CannotProceed</td><td>Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.One possible reason for this exception is that a Name Server holding one or more of the name bindings within a compound name is currently unavailable.</td></tr><tr><td>InvalidName</td><td>Indicates that the name is invalid. This implementation disallows zero length names only.</td></tr><tr><td>NotEmpty</td><td>Indicates that a naming context has bindings.</td></tr><tr><td>NotFound</td><td>Indicates that the name does not identify a binding or that the binding is not of the type required for the requested operations.</td></tr></table>

# APPENDICES

# Appendix

# A

# Examples’ Source Code

Code examples shown in this Guide are taken from an example application which is supplied with the product. The example application is supplied as source files in examples/cpp/services/naming below the installation directory.

![The image displays a red triangular warning sign with rounded corners. Inside the red border, centered on a white background, is a black exclamation point.](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/d1772dc63d750bc2b71a43f8b6a14e1e2a4a3ec14aac041ff4d9e5b414d795d9.jpg)

This release of the Spectra ORB Lightweight Naming Service does not support the kind property of the CosNaming::NameComponent. Although the supplied examples use the kind property, it is nonetheless ignored by the Service when binding or resolving names.

This supplied code is for demonstration and educational purposes only: users should ascertain for themselves the code’s suitability and usability. It is expected that users will need to make changes to the source code to suit their particular platform and configuration.

The examples do not have all of the error or exception trapping code normally used, for the sake of clarity and brevity. Exceptions and errors must, naturally, be caught and properly handled in a production system.

Appendices

# INDEX

# I n d e x

# C

Configuration Structure . . . . . 16

# E

Embedding the Service. . . . . . 15

Example . . . . . 19

Example Server Module. . . . . . 17

Exceptions . . . . . 29

# I

Interfaces and Datatypes. . . 11

# N

Naming Context . . . . 8

Naming Contexts . . . . . 8

Naming Service

Contexts . . . . 8

example

naming context contents, accessing . . . . . . 13

Naming context. . . . 8

NamingContext Exceptions . . . . 11

NamingContext Methods . . . 11

Note . . . 21

# O

OMG Standard Features . . .

# R

Running from the Command Line . . . . . . . . . . . 19

Index
[🔗 Link to the original document](.spectra-orb-c-edition-lightweight-naming-service-user-guide-2/spectra-orb-c-edition-lightweight-naming-service-user-guide.pdf)