<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>CosNaming_NamingContext</title>
<prepared></prepared>
<docno></docno>
<checked></checked>
<date>1997-06-10</date>
<rev>A</rev>
</header>
<module>CosNaming_NamingContext</module>
<modulesummary>This interface supports different bind and access functions for names in a context.</modulesummary>
<description>
<p>This is the object that defines name scopes, names must be unique within a
naming context. Objects may have multiple names and may exist in multiple
naming contexts. Name context may be named in other contexts and cycles are
permitted.</p>
<p>The type <c>NameComponent</c> used below is defined as:</p>
<code type="none">
-record('CosNaming_NameComponent', {id, kind=""}).
</code>
<p>where <c>id</c> and <c>kind</c> are strings. </p>
<p>The type <c>Binding</c> used below is defined as:</p>
<code type="none">
-record('CosNaming_Binding', {binding_name, binding_type}).
</code>
<p>where <c>binding_name</c> is a Name and <c>binding_type</c> is an enum which
has the values <c>nobject</c> and <c>ncontext</c>.</p>
<p>Both these records are defined in the file <c>CosNaming.hrl</c> and it
is included with:</p>
<code type="none">
-include_lib("orber/COSS/CosNaming/CosNaming.hrl").
</code>
<p>There are a number of exceptions that can be returned from functions in this
interface.</p>
<list type="bulleted">
<item>
<p>NotFound is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_NotFound',
{rest_of_name, why}). </code>
</item>
<item>
<p>CannotProceed is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_CannotProceed',
{rest_of_name, cxt}). </code>
</item>
<item>
<p>InvalidName is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_InvalidName', {}). </code>
</item>
<item>
<p>NotFound is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_NotFound', {}). </code>
</item>
<item>
<p>AlreadyBound is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_AlreadyBound', {}). </code>
</item>
<item>
<p>NotEmpty is defined as </p>
<code type="none">
-record('CosNaming_NamingContext_NotEmpty', {). </code>
</item>
</list>
<p>These exceptions are defined in the file <c>CosNaming_NamingContext.hrl</c> and it
is included with:</p>
<code type="none">
-include_lib("orber/COSS/CosNaming/CosNaming_NamingContext.hrl").
</code>
</description>
<funcs>
<func>
<name>bind(NamingContext, Name, Object) -> Return</name>
<fsummary>Bind a Name to an Object</fsummary>
<type>
<v>NameContext = #objref</v>
<v>Name = [NameComponent]</v>
<v>Object = #objref</v>
<v>Return = ok</v>
</type>
<desc>
<p>Creates a binding of a name and an object in the naming context.
Naming contexts that are bound using <em>bind()</em> do not participate
in name resolution.</p>
</desc>
</func>
<func>
<name>rebind(NamingContext, Name, Object) -> Return</name>
<fsummary>Bind an Object to the Name even if the Name already is bound</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Name = [NameComponent]</v>
<v>Object = #objref</v>
<v>Return = ok</v>
</type>
<desc>
<p>Creates a binding of a name and an object in the naming context even
if the name is already bound. Naming contexts that are bound using
<em>rebind()</em> do not participate in name resolution.</p>
</desc>
</func>
<func>
<name>bind_context(NamingContext1, Name, NamingContex2) -> Return</name>
<fsummary>Bind a Name to an NamingContext</fsummary>
<type>
<v>NamingContext1 = NamingContext2 =#objref</v>
<v>Name = [NameComponent]</v>
<v>Return = ok</v>
</type>
<desc>
<p>The bind_context function creates a binding of a name and a naming context in
the current context.
Naming contexts that are bound using <em>bind_context()</em> participate
in name resolution.</p>
</desc>
</func>
<func>
<name>rebind_context(NamingContext1, Name, NamingContex2) -> Return</name>
<fsummary>Bind an NamingContext to the Name even if the Name already is bound</fsummary>
<type>
<v>NamingContext1 = NamingContext2 =#objref</v>
<v>Name = [NameComponent]</v>
<v>Return = ok</v>
</type>
<desc>
<p>The rebind_context function creates a binding of a name and a naming context in
the current context even if the name already is bound.
Naming contexts that are bound using <em>rebind_context()</em> participate
in name resolution.</p>
</desc>
</func>
<func>
<name>resolve(NamingContext, Name) -> Return</name>
<fsummary>Retrieve an Object bound to Name</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Name = [NameComponent]</v>
<v>Return = Object</v>
<v>Object = #objref</v>
</type>
<desc>
<p>The resolve function is the way to retrieve an object bound to a name in
the naming context. The given name must match exactly the bound name. The
type of the object is not returned, clients are responsible for narrowing
the object to the correct type.</p>
</desc>
</func>
<func>
<name>unbind(NamingContext, Name) -> Return</name>
<fsummary>Remove the binding for a Name</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Name = [NameComponent]</v>
<v>Return = ok</v>
</type>
<desc>
<p>The unbind operation removes a name binding from the naming context.</p>
</desc>
</func>
<func>
<name>new_context(NamingContext) -> Return</name>
<fsummary>Create a new NamingContext</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Return = #objref</v>
</type>
<desc>
<p>The new_context operation creates a new naming context.</p>
</desc>
</func>
<func>
<name>bind_new_context(NamingContext, Name) -> Return</name>
<fsummary>Create a new NamingContext and bind it to a Name</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Name = [NameComponent]</v>
<v>Return = #objref</v>
</type>
<desc>
<p>The new_context operation creates a new naming context and binds it to
Name in the current context.</p>
</desc>
</func>
<func>
<name>destroy(NamingContext) -> Return</name>
<fsummary>Destroy a NamingContext</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>Return = ok</v>
</type>
<desc>
<p>The destroy operation disposes the NamingContext object and removes it from the
name server. The context must be empty e.g. not contain any bindings to be
removed.</p>
</desc>
</func>
<func>
<name>list(NamingContext, HowMany) -> Return</name>
<fsummary>List returns a all bindings in the context</fsummary>
<type>
<v>NamingContext = #objref</v>
<v>HowMany = int()</v>
<v>Return = {ok, BindingList, BindingIterator}</v>
<v>BindingList = [Binding]</v>
<v>BindingIterator = #objref</v>
</type>
<desc>
<p>The list operation returns a BindingList with a number of bindings up-to
HowMany from the context. It also returns a BindinIterator which can be used to
step through the list. If the total number of existing bindings are less
than, or equal to, the <c>HowMany</c> parameter a NIL object reference
is returned.</p>
<p></p>
<note>
<p>One must destroy the BindingIterator, unless it is a NIL object
reference, by using 'BindingIterator':destroy(). Otherwise one can get
dangling objects.</p>
</note>
</desc>
</func>
</funcs>
</erlref>
