← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/orber/doc/src/CosNaming_NamingContext.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/orber/doc/src/CosNaming_NamingContext.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
 
3
 
 
4
<erlref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year>
 
8
      <year>2008</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>CosNaming_NamingContext</title>
 
27
    <prepared></prepared>
 
28
    <docno></docno>
 
29
    <checked></checked>
 
30
    <date>1997-06-10</date>
 
31
    <rev>A</rev>
 
32
  </header>
 
33
  <module>CosNaming_NamingContext</module>
 
34
  <modulesummary>This interface supports different bind and access functions for names in a context.</modulesummary>
 
35
  <description>
 
36
    <p>This is the object that defines name scopes, names must be unique within a 
 
37
      naming context. Objects may have multiple names and may exist in multiple
 
38
      naming contexts. Name context may be named in other contexts and cycles are
 
39
      permitted.</p>
 
40
    <p>The type <c>NameComponent</c> used below is defined as:</p>
 
41
    <code type="none">
 
42
      -record('CosNaming_NameComponent', {id, kind=""}).
 
43
    </code>
 
44
    <p>where <c>id</c> and <c>kind</c> are strings. </p>
 
45
    <p>The type <c>Binding</c> used below is defined as:</p>
 
46
    <code type="none">
 
47
      -record('CosNaming_Binding', {binding_name, binding_type}).
 
48
    </code>
 
49
    <p>where <c>binding_name</c> is a Name and <c>binding_type</c> is an enum which 
 
50
      has the values <c>nobject</c> and <c>ncontext</c>.</p>
 
51
    <p>Both these records are defined in the file <c>CosNaming.hrl</c> and it 
 
52
      is included with:</p>
 
53
    <code type="none">
 
54
      -include_lib("orber/COSS/CosNaming/CosNaming.hrl").
 
55
    </code>
 
56
    <p>There are a number of exceptions that can be returned from functions in this 
 
57
      interface.</p>
 
58
    <list type="bulleted">
 
59
      <item>
 
60
        <p>NotFound is defined as </p>
 
61
        <code type="none">
 
62
-record('CosNaming_NamingContext_NotFound', 
 
63
                      {rest_of_name, why}).        </code>
 
64
      </item>
 
65
      <item>
 
66
        <p>CannotProceed is defined as </p>
 
67
        <code type="none">
 
68
-record('CosNaming_NamingContext_CannotProceed', 
 
69
                      {rest_of_name, cxt}).        </code>
 
70
      </item>
 
71
      <item>
 
72
        <p>InvalidName is defined as </p>
 
73
        <code type="none">
 
74
-record('CosNaming_NamingContext_InvalidName', {}).        </code>
 
75
      </item>
 
76
      <item>
 
77
        <p>NotFound is defined as </p>
 
78
        <code type="none">
 
79
-record('CosNaming_NamingContext_NotFound', {}).        </code>
 
80
      </item>
 
81
      <item>
 
82
        <p>AlreadyBound is defined as </p>
 
83
        <code type="none">
 
84
-record('CosNaming_NamingContext_AlreadyBound', {}).        </code>
 
85
      </item>
 
86
      <item>
 
87
        <p>NotEmpty is defined as </p>
 
88
        <code type="none">
 
89
-record('CosNaming_NamingContext_NotEmpty', {).        </code>
 
90
      </item>
 
91
    </list>
 
92
    <p>These exceptions are defined in the file <c>CosNaming_NamingContext.hrl</c> and it 
 
93
      is included with:</p>
 
94
    <code type="none">
 
95
      -include_lib("orber/COSS/CosNaming/CosNaming_NamingContext.hrl").
 
96
    </code>
 
97
  </description>
 
98
  <funcs>
 
99
    <func>
 
100
      <name>bind(NamingContext, Name, Object) -> Return</name>
 
101
      <fsummary>Bind a Name to an Object</fsummary>
 
102
      <type>
 
103
        <v>NameContext = #objref</v>
 
104
        <v>Name = [NameComponent]</v>
 
105
        <v>Object = #objref</v>
 
106
        <v>Return = ok</v>
 
107
      </type>
 
108
      <desc>
 
109
        <p>Creates a binding of a name and an object in the naming context. 
 
110
          Naming contexts that are bound using <em>bind()</em> do not participate
 
111
          in name resolution.</p>
 
112
      </desc>
 
113
    </func>
 
114
    <func>
 
115
      <name>rebind(NamingContext, Name, Object) -> Return</name>
 
116
      <fsummary>Bind an Object to the Name even if the Name already is bound</fsummary>
 
117
      <type>
 
118
        <v>NamingContext = #objref</v>
 
119
        <v>Name = [NameComponent]</v>
 
120
        <v>Object = #objref</v>
 
121
        <v>Return = ok</v>
 
122
      </type>
 
123
      <desc>
 
124
        <p>Creates a binding of a name and an object in the naming context even
 
125
          if the name is already bound. Naming contexts that are bound using
 
126
          <em>rebind()</em> do not participate in name resolution.</p>
 
127
      </desc>
 
128
    </func>
 
129
    <func>
 
130
      <name>bind_context(NamingContext1, Name, NamingContex2) -> Return</name>
 
131
      <fsummary>Bind a Name to an NamingContext</fsummary>
 
132
      <type>
 
133
        <v>NamingContext1 = NamingContext2 =#objref</v>
 
134
        <v>Name = [NameComponent]</v>
 
135
        <v>Return = ok</v>
 
136
      </type>
 
137
      <desc>
 
138
        <p>The bind_context function creates a binding of a name and a naming context in
 
139
          the current context.
 
140
          Naming contexts that are bound using <em>bind_context()</em> participate
 
141
          in name resolution.</p>
 
142
      </desc>
 
143
    </func>
 
144
    <func>
 
145
      <name>rebind_context(NamingContext1, Name, NamingContex2) -> Return</name>
 
146
      <fsummary>Bind an NamingContext to the Name even if the Name already is bound</fsummary>
 
147
      <type>
 
148
        <v>NamingContext1 = NamingContext2 =#objref</v>
 
149
        <v>Name = [NameComponent]</v>
 
150
        <v>Return = ok</v>
 
151
      </type>
 
152
      <desc>
 
153
        <p>The rebind_context function creates a binding of a name and a naming context in
 
154
          the current context even if the name already is bound.
 
155
          Naming contexts that are bound using <em>rebind_context()</em> participate
 
156
          in name resolution.</p>
 
157
      </desc>
 
158
    </func>
 
159
    <func>
 
160
      <name>resolve(NamingContext, Name) -> Return</name>
 
161
      <fsummary>Retrieve an Object bound to Name</fsummary>
 
162
      <type>
 
163
        <v>NamingContext = #objref</v>
 
164
        <v>Name = [NameComponent]</v>
 
165
        <v>Return = Object</v>
 
166
        <v>Object = #objref</v>
 
167
      </type>
 
168
      <desc>
 
169
        <p>The resolve function is the way to retrieve an object bound to a name in
 
170
          the naming context. The given name must match exactly the bound name. The 
 
171
          type of the object is not returned, clients are responsible for narrowing 
 
172
          the object to the correct type.</p>
 
173
      </desc>
 
174
    </func>
 
175
    <func>
 
176
      <name>unbind(NamingContext, Name) -> Return</name>
 
177
      <fsummary>Remove the binding for a Name</fsummary>
 
178
      <type>
 
179
        <v>NamingContext = #objref</v>
 
180
        <v>Name = [NameComponent]</v>
 
181
        <v>Return = ok</v>
 
182
      </type>
 
183
      <desc>
 
184
        <p>The unbind operation removes a name binding from the naming context.</p>
 
185
      </desc>
 
186
    </func>
 
187
    <func>
 
188
      <name>new_context(NamingContext) -> Return</name>
 
189
      <fsummary>Create a new NamingContext</fsummary>
 
190
      <type>
 
191
        <v>NamingContext = #objref</v>
 
192
        <v>Return = #objref</v>
 
193
      </type>
 
194
      <desc>
 
195
        <p>The new_context operation creates a new naming context.</p>
 
196
      </desc>
 
197
    </func>
 
198
    <func>
 
199
      <name>bind_new_context(NamingContext, Name) -> Return</name>
 
200
      <fsummary>Create a new NamingContext and bind it to a Name</fsummary>
 
201
      <type>
 
202
        <v>NamingContext = #objref</v>
 
203
        <v>Name = [NameComponent]</v>
 
204
        <v>Return = #objref</v>
 
205
      </type>
 
206
      <desc>
 
207
        <p>The new_context operation creates a new naming context and binds it to
 
208
          Name in the current context.</p>
 
209
      </desc>
 
210
    </func>
 
211
    <func>
 
212
      <name>destroy(NamingContext) -> Return</name>
 
213
      <fsummary>Destroy a NamingContext</fsummary>
 
214
      <type>
 
215
        <v>NamingContext = #objref</v>
 
216
        <v>Return = ok</v>
 
217
      </type>
 
218
      <desc>
 
219
        <p>The destroy operation disposes the NamingContext object and removes it from the 
 
220
          name server. The context must be empty e.g. not contain any bindings to be 
 
221
          removed.</p>
 
222
      </desc>
 
223
    </func>
 
224
    <func>
 
225
      <name>list(NamingContext, HowMany) -> Return</name>
 
226
      <fsummary>List returns a all bindings in the context</fsummary>
 
227
      <type>
 
228
        <v>NamingContext = #objref</v>
 
229
        <v>HowMany = int()</v>
 
230
        <v>Return = {ok, BindingList, BindingIterator}</v>
 
231
        <v>BindingList = [Binding]</v>
 
232
        <v>BindingIterator = #objref</v>
 
233
      </type>
 
234
      <desc>
 
235
        <p>The list operation returns a BindingList with a number of bindings up-to
 
236
          HowMany from the context. It also returns a BindinIterator which can be used to
 
237
          step through the list. If the total number of existing bindings are less
 
238
          than, or equal to, the <c>HowMany</c> parameter a NIL object reference
 
239
          is returned.</p>
 
240
        <p></p>
 
241
        <note>
 
242
          <p>One must destroy the BindingIterator, unless it is a NIL object
 
243
            reference, by using 'BindingIterator':destroy(). Otherwise one can get
 
244
            dangling objects.</p>
 
245
        </note>
 
246
      </desc>
 
247
    </func>
 
248
  </funcs>
 
249
  
 
250
</erlref>
 
251