<?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>