1
2
3
4
5
6
7
8
9
10 package nl.tudelft.simulation.naming;
11
12 import java.rmi.Remote;
13 import java.rmi.RemoteException;
14 import java.util.Hashtable;
15
16 import javax.naming.Binding;
17 import javax.naming.CompoundName;
18 import javax.naming.ContextNotEmptyException;
19 import javax.naming.Name;
20 import javax.naming.NameAlreadyBoundException;
21 import javax.naming.NameClassPair;
22 import javax.naming.NameNotFoundException;
23 import javax.naming.NameParser;
24 import javax.naming.NamingEnumeration;
25 import javax.naming.NamingException;
26 import javax.naming.NotContextException;
27 import javax.naming.OperationNotSupportedException;
28
29 import nl.tudelft.simulation.naming.listener.RemoteContextListenerInterface;
30
31 /***
32 * <p>
33 * (c) copyright 2003 <a href="http://www.simulation.tudelft.nl">Delft
34 * University of Technology </a>, the Netherlands. <br>
35 * See for project information <a
36 * href="http://www.simulation.tudelft.nl">www.simulation.tudelft.nl </a> <br>
37 * License of use: <a href="http://www.gnu.org/copyleft/gpl.html">General Public
38 * License (GPL) </a>, no warranty <br>
39 *
40 * @author <a href="http://www.tbm.tudelft.nl/webstaf/peterja/index.htm">Peter
41 * Jacobs </a>
42 * @version 1.1 Apr 7, 2004
43 * @since 1.4
44 */
45 public interface RemoteContextInterface extends Remote
46 {
47 /***
48 * Constant defining the first part of properties wrapped by our remote
49 * construction.
50 */
51 String WRAPPED_PREFIX = "wrapped.naming";
52
53 /***
54 * Adds a listener for receiving naming events fired when the object(s)
55 * identified by a target and scope changes.
56 *
57 * The event source of those events is this context. See the class
58 * description for a discussion on event source and target. See the
59 * descriptions of the constants <tt>OBJECT_SCOPE</tt>,
60 * <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how
61 * <tt>scope</tt> affects the registration.
62 * <p>
63 * <tt>target</tt> needs to name a context only when <tt>scope</tt> is
64 * <tt>ONELEVEL_SCOPE</tt>.<tt>target</tt> may name a non-context if
65 * <tt>scope</tt> is either <tt>OBJECT_SCOPE</tt> or
66 * <tt>SUBTREE_SCOPE</tt>. Using <tt>SUBTREE_SCOPE</tt> for a
67 * non-context might be useful, for example, if the caller does not know in
68 * advance whether <tt>target</tt> is a context and just wants to register
69 * interest in the (possibly degenerate subtree) rooted at <tt>target</tt>.
70 * <p>
71 * When the listener is notified of an event, the listener may in invoked in
72 * a thread other than the one in which <tt>addNamingListener()</tt> is
73 * executed. Care must be taken when multiple threads are accessing the same
74 * <tt>EventContext</tt> concurrently. See the <a
75 * href=package-summary.html#THREADING>package description </a> for more
76 * information on threading issues.
77 *
78 * @param target A nonnull name to be resolved relative to this context.
79 * @param scope One of <tt>OBJECT_SCOPE</tt>,<tt>ONELEVEL_SCOPE</tt>,
80 * or <tt>SUBTREE_SCOPE</tt>.
81 * @param l The nonnull listener.
82 * @exception NamingException If a problem was encountered while adding the
83 * listener.
84 * @exception RemoteException on network exception
85 */
86 public void addNamingListener(Name target, int scope,
87 RemoteContextListenerInterface l) throws RemoteException,
88 NamingException;
89
90
91 /***
92 * Adds a listener for receiving naming events fired when the object named
93 * by the string target name and scope changes.
94 *
95 * See the overload that accepts a <tt>Name</tt> for details.
96 *
97 * @param target The nonnull string name of the object resolved relative to
98 * this context.
99 * @param scope One of <tt>OBJECT_SCOPE</tt>,<tt>ONELEVEL_SCOPE</tt>,
100 * or <tt>SUBTREE_SCOPE</tt>.
101 * @param l The nonnull listener.
102 * @exception NamingException If a problem was encountered while adding the
103 * listener.
104 * @exception RemoteException on network exception
105 */
106 public void addNamingListener(String target, int scope,
107 RemoteContextListenerInterface l) throws NamingException,
108 RemoteException;
109
110
111 /***
112 * Removes a listener from receiving naming events fired by this
113 * <tt>EventContext</tt>. The listener may have registered more than once
114 * with this <tt>EventContext</tt>, perhaps with different target/scope
115 * arguments. After this method is invoked, the listener will no longer
116 * receive events with this <tt>EventContext</tt> instance as the event
117 * source (except for those events already in the process of being
118 * dispatched). If the listener was not, or is no longer, registered with
119 * this <tt>EventContext</tt> instance, this method does not do anything.
120 *
121 * @param l The nonnull listener.
122 * @exception NamingException If a problem was encountered while removing
123 * the listener.
124 * @exception RemoteException on network exception
125 */
126 public void removeNamingListener(RemoteContextListenerInterface l)
127 throws NamingException, RemoteException;
128
129
130 /***
131 * Determines whether a listener can register interest in a target that does
132 * not exist.
133 *
134 * @return true if the target must exist; false if the target need not
135 * exist.
136 * @exception NamingException If the context's behavior in this regard
137 * cannot be determined.
138 * @exception RemoteException on network exception
139 */
140 public boolean targetMustExist() throws NamingException, RemoteException;
141
142 /***
143 * Retrieves the named object. If <tt>name</tt> is empty, returns a new
144 * instance of this context (which represents the same naming context as
145 * this context, but its environment may be modified independently and it
146 * may be accessed concurrently).
147 *
148 * @param name the name of the object to look up
149 * @return the object bound to <tt>name</tt>
150 * @throws NamingException if a naming exception is encountered
151 * @exception RemoteException on network exception
152 *
153 * @see #lookup(String)
154 * @see #lookupLink(Name)
155 */
156 public Object lookup(Name name) throws NamingException, RemoteException;
157
158 /***
159 * Retrieves the named object. See {@link #lookup(Name)}for details.
160 *
161 * @param name the name of the object to look up
162 * @return the object bound to <tt>name</tt>
163 * @throws NamingException if a naming exception is encountered
164 * @exception RemoteException on network exception
165 */
166 public Object lookup(String name) throws NamingException, RemoteException;
167
168 /***
169 * Binds a name to an object. All intermediate contexts and the target
170 * context (that named by all but terminal atomic component of the name)
171 * must already exist.
172 *
173 * @param name the name to bind; may not be empty
174 * @param obj the object to bind; possibly null
175 * @throws javax.naming.directory.InvalidAttributesException if object did
176 * not supply all mandatory attributes
177 * @throws NamingException if a naming exception is encountered
178 * @exception RemoteException on network exception
179 *
180 * @see #bind(String, Object)
181 * @see #rebind(Name, Object)
182 * @see javax.naming.directory.DirContext#bind(Name, Object,
183 * javax.naming.directory.Attributes)
184 */
185 public void bind(Name name, Object obj) throws NamingException,
186 RemoteException;
187
188 /***
189 * Binds a name to an object. See {@link #bind(Name, Object)}for details.
190 *
191 * @param name the name to bind; may not be empty
192 * @param obj the object to bind; possibly null
193 * @throws javax.naming.directory.InvalidAttributesException if object did
194 * not supply all mandatory attributes
195 * @throws NamingException if a naming exception is encountered
196 * @exception RemoteException on network exception
197 */
198 public void bind(String name, Object obj) throws NamingException,
199 RemoteException;
200
201 /***
202 * Binds a name to an object, overwriting any existing binding. All
203 * intermediate contexts and the target context (that named by all but
204 * terminal atomic component of the name) must already exist.
205 *
206 * <p>
207 * If the object is a <tt>DirContext</tt>, any existing attributes
208 * associated with the name are replaced with those of the object.
209 * Otherwise, any existing attributes associated with the name remain
210 * unchanged.
211 *
212 * @param name the name to bind; may not be empty
213 * @param obj the object to bind; possibly null
214 * @throws javax.naming.directory.InvalidAttributesException if object did
215 * not supply all mandatory attributes
216 * @throws NamingException if a naming exception is encountered
217 * @exception RemoteException on network exception
218 *
219 * @see #rebind(String, Object)
220 * @see #bind(Name, Object)
221 * @see javax.naming.directory.DirContext#rebind(Name, Object,
222 * javax.naming.directory.Attributes)
223 * @see javax.naming.directory.DirContext
224 */
225 public void rebind(Name name, Object obj) throws NamingException,
226 RemoteException;
227
228 /***
229 * Binds a name to an object, overwriting any existing binding. See
230 * {@link #rebind(Name, Object)}for details.
231 *
232 * @param name the name to bind; may not be empty
233 * @param obj the object to bind; possibly null
234 * @throws javax.naming.directory.InvalidAttributesException if object did
235 * not supply all mandatory attributes
236 * @throws NamingException if a naming exception is encountered
237 * @exception RemoteException on network exception
238 */
239 public void rebind(String name, Object obj) throws NamingException,
240 RemoteException;
241
242 /***
243 * Unbinds the named object. Removes the terminal atomic name in
244 * <code>name</code> from the target context--that named by all but the
245 * terminal atomic part of <code>name</code>.
246 *
247 * <p>
248 * This method is idempotent. It succeeds even if the terminal atomic name
249 * is not bound in the target context, but throws
250 * <tt>NameNotFoundException</tt> if any of the intermediate contexts do
251 * not exist.
252 *
253 * <p>
254 * Any attributes associated with the name are removed. Intermediate
255 * contexts are not changed.
256 *
257 * @param name the name to unbind; may not be empty
258 * @throws NamingException if a naming exception is encountered
259 * @exception RemoteException on network exception
260 * @see #unbind(String)
261 */
262 public void unbind(Name name) throws NamingException, RemoteException;
263
264 /***
265 * Unbinds the named object. See {@link #unbind(Name)}for details.
266 *
267 * @param name the name to unbind; may not be empty
268 * @exception RemoteException on network exception
269 * @throws NamingException if a naming exception is encountered
270 */
271 public void unbind(String name) throws NamingException, RemoteException;
272
273 /***
274 * Binds a new name to the object bound to an old name, and unbinds the old
275 * name. Both names are relative to this context. Any attributes associated
276 * with the old name become associated with the new name. Intermediate
277 * contexts of the old name are not changed.
278 *
279 * @param oldName the name of the existing binding; may not be empty
280 * @param newName the name of the new binding; may not be empty
281 * @throws NamingException if a naming exception is encountered
282 * @exception RemoteException on network exception
283 *
284 * @see #rename(String, String)
285 * @see #bind(Name, Object)
286 * @see #rebind(Name, Object)
287 */
288 public void rename(Name oldName, Name newName) throws NamingException,
289 RemoteException;
290
291 /***
292 * Binds a new name to the object bound to an old name, and unbinds the old
293 * name. See {@link #rename(Name, Name)}for details.
294 *
295 * @param oldName the name of the existing binding; may not be empty
296 * @param newName the name of the new binding; may not be empty
297 * @throws NamingException if a naming exception is encountered
298 * @exception RemoteException on network exception
299 */
300 public void rename(String oldName, String newName) throws NamingException,
301 RemoteException;
302
303 /***
304 * Enumerates the names bound in the named context, along with the class
305 * names of objects bound to them. The contents of any subcontexts are not
306 * included.
307 *
308 * <p>
309 * If a binding is added to or removed from this context, its effect on an
310 * enumeration previously returned is undefined.
311 *
312 * @param name the name of the context to list
313 * @return an enumeration of the names and class names of the bindings in
314 * this context. Each element of the enumeration is of type
315 * <tt>NameClassPair</tt>.
316 * @throws NamingException if a naming exception is encountered
317 * @exception RemoteException on network exception
318 *
319 * @see #list(String)
320 * @see #listBindings(Name)
321 * @see NameClassPair
322 */
323 public NamingEnumeration list(Name name) throws NamingException,
324 RemoteException;
325
326 /***
327 * Enumerates the names bound in the named context, along with the class
328 * names of objects bound to them. See {@link #list(Name)}for details.
329 *
330 * @param name the name of the context to list
331 * @return an enumeration of the names and class names of the bindings in
332 * this context. Each element of the enumeration is of type
333 * <tt>NameClassPair</tt>.
334 * @throws NamingException if a naming exception is encountered
335 * @exception RemoteException on network exception
336 */
337 public NamingEnumeration list(String name) throws NamingException,
338 RemoteException;
339
340 /***
341 * Enumerates the names bound in the named context, along with the objects
342 * bound to them. The contents of any subcontexts are not included.
343 *
344 * <p>
345 * If a binding is added to or removed from this context, its effect on an
346 * enumeration previously returned is undefined.
347 *
348 * @param name the name of the context to list
349 * @return an enumeration of the bindings in this context. Each element of
350 * the enumeration is of type <tt>Binding</tt>.
351 * @throws NamingException if a naming exception is encountered
352 * @exception RemoteException on network exception
353 *
354 * @see #listBindings(String)
355 * @see #list(Name)
356 * @see Binding
357 */
358 public NamingEnumeration listBindings(Name name) throws NamingException,
359 RemoteException;
360
361 /***
362 * Enumerates the names bound in the named context, along with the objects
363 * bound to them. See {@link #listBindings(Name)}for details.
364 *
365 * @param name the name of the context to list
366 * @return an enumeration of the bindings in this context. Each element of
367 * the enumeration is of type <tt>Binding</tt>.
368 * @throws NamingException if a naming exception is encountered
369 * @exception RemoteException on network exception
370 */
371 public NamingEnumeration listBindings(String name) throws NamingException,
372 RemoteException;
373
374 /***
375 * Destroys the named context and removes it from the namespace. Any
376 * attributes associated with the name are also removed. Intermediate
377 * contexts are not destroyed.
378 *
379 * <p>
380 * This method is idempotent. It succeeds even if the terminal atomic name
381 * is not bound in the target context, but throws
382 * <tt>NameNotFoundException</tt> if any of the intermediate contexts do
383 * not exist.
384 *
385 * <p>
386 * In a federated naming system, a context from one naming system may be
387 * bound to a name in another. One can subsequently look up and perform
388 * operations on the foreign context using a composite name. However, an
389 * attempt destroy the context using this composite name will fail with
390 * <tt>NotContextException</tt>, because the foreign context is not a
391 * "subcontext" of the context in which it is bound. Instead, use
392 * <tt>unbind()</tt> to remove the binding of the foreign context.
393 * Destroying the foreign context requires that the
394 * <tt>destroySubcontext()</tt> be performed on a context from the foreign
395 * context's "native" naming system.
396 *
397 * @param name the name of the context to be destroyed; may not be empty
398 * @throws NameNotFoundException if an intermediate context does not exist
399 * @throws NotContextException if the name is bound but does not name a
400 * context, or does not name a context of the appropriate type
401 * @throws ContextNotEmptyException if the named context is not empty
402 * @throws NamingException if a naming exception is encountered
403 * @exception RemoteException on network exception
404 *
405 * @see #destroySubcontext(String)
406 */
407 public void destroySubcontext(Name name) throws NamingException,
408 RemoteException;
409
410 /***
411 * Destroys the named context and removes it from the namespace. See
412 * {@link #destroySubcontext(Name)}for details.
413 *
414 * @param name the name of the context to be destroyed; may not be empty
415 * @throws NameNotFoundException if an intermediate context does not exist
416 * @throws NotContextException if the name is bound but does not name a
417 * context, or does not name a context of the appropriate type
418 * @throws ContextNotEmptyException if the named context is not empty
419 * @throws NamingException if a naming exception is encountered
420 * @exception RemoteException on network exception
421 */
422 public void destroySubcontext(String name) throws NamingException,
423 RemoteException;
424
425 /***
426 * Creates and binds a new context. Creates a new context with the given
427 * name and binds it in the target context (that named by all but terminal
428 * atomic component of the name). All intermediate contexts and the target
429 * context must already exist.
430 *
431 * @param name the name of the context to create; may not be empty
432 * @return the newly created context
433 *
434 * @throws NameAlreadyBoundException if name is already bound
435 * @throws javax.naming.directory.InvalidAttributesException if creation of
436 * the subcontext requires specification of mandatory attributes
437 * @throws NamingException if a naming exception is encountered
438 * @exception RemoteException on network exception
439 *
440 * @see #createSubcontext(String)
441 */
442 public RemoteContextInterface createSubcontext(Name name)
443 throws NamingException, RemoteException;
444
445 /***
446 * Creates and binds a new context. See {@link #createSubcontext(Name)}for
447 * details.
448 *
449 * @param name the name of the context to create; may not be empty
450 * @return the newly created context
451 *
452 * @throws NameAlreadyBoundException if name is already bound
453 * @throws javax.naming.directory.InvalidAttributesException if creation of
454 * the subcontext requires specification of mandatory attributes
455 * @throws NamingException if a naming exception is encountered
456 * @exception RemoteException on network exception
457 */
458 public RemoteContextInterface createSubcontext(String name)
459 throws NamingException, RemoteException;
460
461 /***
462 * Retrieves the named object, following links except for the terminal
463 * atomic component of the name. If the object bound to <tt>name</tt> is
464 * not a link, returns the object itself.
465 *
466 * @param name the name of the object to look up
467 * @return the object bound to <tt>name</tt>, not following the terminal
468 * link (if any).
469 * @throws NamingException if a naming exception is encountered
470 * @exception RemoteException on network exception
471 *
472 * @see #lookupLink(String)
473 */
474 public Object lookupLink(Name name) throws NamingException, RemoteException;
475
476 /***
477 * Retrieves the named object, following links except for the terminal
478 * atomic component of the name. See {@link #lookupLink(Name)}for details.
479 *
480 * @param name the name of the object to look up
481 * @return the object bound to <tt>name</tt>, not following the terminal
482 * link (if any)
483 * @throws NamingException if a naming exception is encountered
484 * @exception RemoteException on network exception
485 */
486 public Object lookupLink(String name) throws NamingException,
487 RemoteException;
488
489 /***
490 * Retrieves the parser associated with the named context. In a federation
491 * of namespaces, different naming systems will parse names differently.
492 * This method allows an application to get a parser for parsing names into
493 * their atomic components using the naming convention of a particular
494 * naming system. Within any single naming system, <tt>NameParser</tt>
495 * objects returned by this method must be equal (using the
496 * <tt>equals()</tt> test).
497 *
498 * @param name the name of the context from which to get the parser
499 * @return a name parser that can parse compound names into their atomic
500 * components
501 * @throws NamingException if a naming exception is encountered
502 * @exception RemoteException on network exception
503 *
504 * @see #getNameParser(String)
505 * @see CompoundName
506 */
507 public NameParser getNameParser(Name name) throws NamingException,
508 RemoteException;
509
510 /***
511 * Retrieves the parser associated with the named context. See
512 * {@link #getNameParser(Name)}for details.
513 *
514 * @param name the name of the context from which to get the parser
515 * @return a name parser that can parse compound names into their atomic
516 * components
517 * @throws NamingException if a naming exception is encountered
518 * @exception RemoteException on network exception
519 */
520 public NameParser getNameParser(String name) throws NamingException,
521 RemoteException;
522
523 /***
524 * Composes the name of this context with a name relative to this context.
525 * Given a name (<code>name</code>) relative to this context, and the
526 * name (<code>prefix</code>) of this context relative to one of its
527 * ancestors, this method returns the composition of the two names using the
528 * syntax appropriate for the naming system(s) involved. That is, if
529 * <code>name</code> names an object relative to this context, the result
530 * is the name of the same object, but relative to the ancestor context.
531 * None of the names may be null.
532 * <p>
533 * For example, if this context is named "wiz.com" relative to the initial
534 * context, then
535 *
536 * <pre>
537 * composeName("east", "wiz.com")
538 * </pre>
539 *
540 * might return <code>"east.wiz.com"</code>. If instead this context is
541 * named "org/research", then
542 *
543 * <pre>
544 * composeName("user/jane", "org/research")
545 * </pre>
546 *
547 * might return <code>"org/research/user/jane"</code> while
548 *
549 * <pre>
550 * composeName("user/jane", "research")
551 * </pre>
552 *
553 * returns <code>"research/user/jane"</code>.
554 *
555 * @param name a name relative to this context
556 * @param prefix the name of this context relative to one of its ancestors
557 * @return the composition of <code>prefix</code> and <code>name</code>
558 * @throws NamingException if a naming exception is encountered
559 * @exception RemoteException on network exception
560 *
561 * @see #composeName(String, String)
562 */
563 public Name composeName(Name name, Name prefix) throws NamingException,
564 RemoteException;
565
566 /***
567 * Composes the name of this context with a name relative to this context.
568 * See {@link #composeName(Name, Name)}for details.
569 *
570 * @param name a name relative to this context
571 * @param prefix the name of this context relative to one of its ancestors
572 * @return the composition of <code>prefix</code> and <code>name</code>
573 * @throws NamingException if a naming exception is encountered
574 * @exception RemoteException on network exception
575 */
576 public String composeName(String name, String prefix)
577 throws NamingException, RemoteException;
578
579 /***
580 * Adds a new environment property to the environment of this context. If
581 * the property already exists, its value is overwritten. See class
582 * description for more details on environment properties.
583 *
584 * @param propName the name of the environment property to add; may not be
585 * null
586 * @param propVal the value of the property to add; may not be null
587 * @return the previous value of the property, or null if the property was
588 * not in the environment before
589 * @throws NamingException if a naming exception is encountered
590 * @exception RemoteException on network exception
591 *
592 * @see #getEnvironment()
593 * @see #removeFromEnvironment(String)
594 */
595 public Object addToEnvironment(String propName, Object propVal)
596 throws NamingException, RemoteException;
597
598 /***
599 * Removes an environment property from the environment of this context. See
600 * class description for more details on environment properties.
601 *
602 * @param propName the name of the environment property to remove; may not
603 * be null
604 * @return the previous value of the property, or null if the property was
605 * not in the environment
606 * @throws NamingException if a naming exception is encountered
607 * @exception RemoteException on network exception
608 *
609 * @see #getEnvironment()
610 * @see #addToEnvironment(String, Object)
611 */
612 public Object removeFromEnvironment(String propName)
613 throws NamingException, RemoteException;
614
615 /***
616 * Retrieves the environment in effect for this context. See class
617 * description for more details on environment properties.
618 *
619 * <p>
620 * The caller should not make any changes to the object returned: their
621 * effect on the context is undefined. The environment of this context may
622 * be changed using <tt>addToEnvironment()</tt> and
623 * <tt>removeFromEnvironment()</tt>.
624 *
625 * @return the environment of this context; never null
626 * @throws NamingException if a naming exception is encountered
627 * @exception RemoteException on network exception
628 *
629 * @see #addToEnvironment(String, Object)
630 * @see #removeFromEnvironment(String)
631 */
632 public Hashtable getEnvironment() throws NamingException, RemoteException;
633
634 /***
635 * Closes this context. This method releases this context's resources
636 * immediately, instead of waiting for them to be released automatically by
637 * the garbage collector.
638 *
639 * <p>
640 * This method is idempotent: invoking it on a context that has already been
641 * closed has no effect. Invoking any other method on a closed context is
642 * not allowed, and results in undefined behaviour.
643 *
644 * @throws NamingException if a naming exception is encountered
645 * @exception RemoteException on network exception
646 */
647 public void close() throws NamingException, RemoteException;
648
649 /***
650 * Retrieves the full name of this context within its own namespace.
651 *
652 * <p>
653 * Many naming services have a notion of a "full name" for objects in their
654 * respective namespaces. For example, an LDAP entry has a distinguished
655 * name, and a DNS record has a fully qualified name. This method allows the
656 * client application to retrieve this name. The string returned by this
657 * method is not a JNDI composite name and should not be passed directly to
658 * context methods. In naming systems for which the notion of full name does
659 * not make sense, <tt>OperationNotSupportedException</tt> is thrown.
660 *
661 * @return this context's name in its own namespace; never null
662 * @throws OperationNotSupportedException if the naming system does not have
663 * the notion of a full name
664 * @throws NamingException if a naming exception is encountered
665 * @exception RemoteException on network exception
666 *
667 * @since 1.3
668 */
669 public String getNameInNamespace() throws NamingException, RemoteException;
670 }