aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/CosNaming_NamingContext.xml
blob: 3c620024a9654551020fe5b50eb705b30bd5a540 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
<?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>