Package `org.omg.CosNaming`

The package org.omg.CosNaming specifies the naming service for Java IDL.

The package and all its classes and interfaces were generated by running the tool idltojava on the file nameservice.idl, which is a module written in OMG IDL.

Interfaces

The package org.omg.CosNaming contains two public interfaces and several auxiliary classes.

The interfaces are:

NamingContext
BindingIterator

These two interfaces provide the means to bind/unbind names and object references, to retrieve bound object references, and to iterate through a list of bindings. The NamingContext interface supplies the main functionality for the naming service, and BindingIterator provides a means of iterating through a list of name/object reference bindings.

Auxiliary Classes

In order to map an OMG IDL interface to the Java programming language, the idltojava compiler creates Java classes that can be thought of as auxiliary classes. Comments for the generated auxiliary classes used by the interfaces NamingContext and BindingIterator are included here.

Classes Used by `NamingContext` and `BindingIterator`

The following are classes used by the naming service. (Helper and holder classes generated for each of them are discussed below.)

public final class NameComponent -- a building block for names. (Names are bound to object references in a naming context.)
A name is an array of one or more NameComponent objects. A name with a single NameComponent is called a simple name; a name with multiple NameComponent objects is called a compound name.
A NameComponent object consists of two fields:
1. id -- a String used as an identifier
2. kind -- a String that can be used for any descriptive purpose. Its importance is that it can be used to describe an object without affecting syntax. The C programming language, for example, uses the the syntactic convention of appending the extension ".c" to a file name to indicate that it is a source code file. In a NameComponent object, the kind field can be used to describe the type of object rather than a file extension or some other syntactic convention. Examples of the value of the kind field include the strings "c_source", "object_code", "executable", "postscript", and "". It is not unusual for the kind field to be the empty string.
In a name, each NameComponent object except the last denotes a NamingContext object; the last NameComponent object denotes the bound object reference. This is similar to a path name, in which the last name is the file name, and all names before it are directory names.
public final class Binding -- an object that associates a name with an object reference or a naming context. A Binding object has two fields:
1. binding_name - an array of one or more NameComponent objects that represents the bound name
2. binding_type - a BindingType object indicating whether the binding is between a name and an object reference or between a name and a naming context
The interface NamingContext has methods for binding/unbinding names with object references or naming contexts, for listing bindings, and for resolving bindings (given a name, the method resolve returns the object reference bound to it).
public final class BindingType -- an object that specifies whether the given Binding object is a binding between a name and an object reference (that is, not a naming context) or between a name and a naming context.
The classBindingType consists of two methods and four constants. Two of these constants are BindingType objects, and two are ints.
The BindingType objects can be passed to the constructor for the class Binding or used as parameters or return values. These BindingType objects are:
- public static final BindingType nobject -- to indicate that the binding is with an object reference
- public static final BindingType ncontext -- to indicate that the binding is with a naming context
The int constants can be supplied to the method from_int to create BindingType objects, or they can be return values for the method value. These constants are:
- public static final int _nobject
- public static final int _ncontext
If the method from_int is supplied with anything other than the ints _nobject or _ncontext, it will throw the exception org.omg.CORBA.BAD_PARAM.
Usage is as follows:
```
       BindingType btObject = from_int(_nobject);
       BindingType btContext = from_int(_ncontext);
    
```
The variable btObject refers to a BindingType object initialized to represent a binding with an object reference. The variable btContext refers to a BindingType object initialized to represent a binding with a NamingContex object.
The method value returns either _nobject or _ncontext, so in the following line of code, the variable bt will contain _nobject or _ncontext:
```
       int bt = BindingType.value();
    
```

Holder Classes

OMG IDL uses OUT and INOUT parameters for returning values from operations. The mapping to the Java programming language, which does not have OUT and INOUT parameters, creates a special class for each type, called a holder class. An instance of a holder class can be passed to a Java method as a parameter, and a value can be assigned to its value field. This allows it to perform the function of an OUT or INOUT parameter.

The following holder classes are generated for the package org.omg.CosNaming:

NamingContextHolder
BindingIteratorHolder
BindingHolder
BindingListHolder
BindingTypeHolder
NameComponentHolder
NameHolder

Note that in the org.omg.CORBA package, there is a holder class for each of the basic Java types: IntHolder, ShortHolder, StringHolder, and so on.

Note also that there is a NameHolder class even though there is no Name class; similarly, there is a BindingListHolder class even though there is no BindingList class. This is true because in the OMG IDL interface, Name and BindingList are typedefs. There is no mapping from an IDL typedef to a Java construct, but holder classes are generated if the typedef is for a sequence or an array. As mapped to the Java programming language, Name is an array of NameComponent objects, and a BindingList is an array of Binding objects. All holder classes have at least two constructors and one field:

value field -- an instance of the type being used as an OUT or INOUT parameter. For example, the value of a NamingContextHolder will be a NamingContext object.
default constructor -- a constructor that creates a new holder object initialized with the default value for the type. For example, a new BindingHolder object created with the default constructor will have its value field set to null because that is the default value for an object. Other defaults are false for boolean, 0 for numeric and char types, and null for object references.
constructor from an instance -- a constructor that creates a new holder object whose value field is initialized with the instance supplied

A holder class for a user-defined type (a Java class) has three more methods, but application developers do not use them directly.

Helper Classes

Helper classes, which are generated for all user-defined types in an OMG IDL interface, supply static methods needed to manipulate those types.

There is only one method in a helper class that an application programmer uses: the method narrow. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a narrow method, so in the CosNaming package, only the classes NamingContextHelper and BindingIteratorHelper have a narrow method.

public static NamingContext narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a NamingContext object
public static BindingIterator narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a BindingIterator object

Package `org.omg.CosNaming.NamingContextPackage`

This package supplies Helper and Holder classes for the exceptions used in the package org.omg.CosNaming and for the class NotFoundReason, which supplies a reason for the exception NotFound.

There are Helper and Holder classes for the following exceptions:

AlreadyBound
CannotProceed
InvalidName
NotEmpty
NotFound

Package org.omg.CosNaming