<?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>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>

