Source for javax.naming.Context

   1: /* Context.java -- A naming context
   2:    Copyright (C) 2000, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.naming;
  40: 
  41: import java.util.Hashtable;
  42: 
  43: import javax.naming.directory.InvalidAttributesException;
  44: 
  45: public interface Context
  46: {
  47:   /**
  48:    * Property with name of the inital context factory to use
  49:    */
  50:   String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
  51: 
  52:   /**
  53:    * Property with colon-separated list of object factories to use.
  54:    */
  55:   String OBJECT_FACTORIES = "java.naming.factory.object";
  56: 
  57:   /**
  58:    * Property with colon-separated list of state factories to use.
  59:    */
  60:   String STATE_FACTORIES = "java.naming.factory.state";
  61: 
  62:   /**
  63:    * Property with colon-separated list of package prefixes to use.
  64:    */
  65:   String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
  66: 
  67:   /**
  68:    * Property with URL specifying configuration for the service provider to use.
  69:    */
  70:   String PROVIDER_URL = "java.naming.provider.url";
  71: 
  72:   /**
  73:    * Property with the DNS host and domain names to use.
  74:    */
  75:   String DNS_URL = "java.naming.dns.url";
  76: 
  77:   /**
  78:    * Property with the authoritativeness of the service requested.
  79:    */
  80:   String AUTHORITATIVE = "java.naming.authoritative";
  81: 
  82:   /**
  83:    * Property with the batch size to use when returning data via the service's
  84:    * protocol.
  85:    */
  86:   String BATCHSIZE = "java.naming.batchsize";
  87: 
  88:   /**
  89:    * Property defining how referrals encountered by the service provider are to
  90:    * be processed.
  91:    */
  92:   String REFERRAL = "java.naming.referral";
  93: 
  94:   /**
  95:    * Property specifying the security protocol to use.
  96:    */
  97:   String SECURITY_PROTOCOL = "java.naming.security.protocol";
  98: 
  99:   /**
 100:    * Property specifying the security level to use.
 101:    */
 102:   String SECURITY_AUTHENTICATION = "java.naming.security.authentication";
 103: 
 104:   /**
 105:    * Property for the identity of the principal for authenticating the caller to
 106:    * the service.
 107:    */
 108:   String SECURITY_PRINCIPAL = "java.naming.security.principal";
 109: 
 110:   /**
 111:    * Property specifying the credentials of the principal for authenticating the
 112:    * caller to the service.
 113:    */
 114:   String SECURITY_CREDENTIALS = "java.naming.security.credentials";
 115: 
 116:   /**
 117:    * Property for specifying the preferred language to use with the service.
 118:    */
 119:   String LANGUAGE = "java.naming.language";
 120: 
 121:   /**
 122:    * Property for the initial context constructor to use when searching for
 123:    * other properties.
 124:    */
 125:   String APPLET = "java.naming.applet";
 126: 
 127:   /**
 128:    * Give the specified name for the specified object. The passed name must not
 129:    * be already bound to some other object.
 130:    * 
 131:    * @param name the name that will be given to the object (in the scope of this
 132:    *          context).
 133:    * @param obj the object being named.
 134:    * @throws NameAlreadyBoundException if this name is already used to name some
 135:    *           object.
 136:    * @throws InvalidAttributesException if the object does not supply all
 137:    *           required attributes.
 138:    * @throws NamingException if the naming operation has failed due other
 139:    *           reasons.
 140:    */
 141:   void bind(Name name, Object obj) throws NamingException;
 142: 
 143:   /**
 144:    * Give the specified name for the specified object. The passed name must not
 145:    * be already bound to some other object.
 146:    * 
 147:    * @param name the name that will be given to the object (in the scope of this
 148:    *          context).
 149:    * @param obj the object being named.
 150:    * @throws NameAlreadyBoundException if this name is already used to name some
 151:    *           object.
 152:    * @throws InvalidAttributesException if the object does not supply all
 153:    *           required attributes.
 154:    * @throws NamingException if the naming operation has failed due other
 155:    *           reasons.
 156:    */
 157:   void bind(String name, Object obj) throws NamingException;
 158: 
 159:   /**
 160:    * Gets the previously named object by name. If the passed name is empty, the
 161:    * method should return a cloned instance of this naming context.
 162:    * 
 163:    * @param name the name of the object being searched in this context
 164:    * @return the named object
 165:    * @throws NamingException if the naming fails.
 166:    */
 167:   Object lookup(Name name) throws NamingException;
 168: 
 169:   /**
 170:    * Gets the previously named object by name. If the passed name is empty, the
 171:    * method should return a cloned instance of this naming context.
 172:    * 
 173:    * @param name the name of the object being searched in this context
 174:    * @return the named object
 175:    * @throws NamingException if the naming fails.
 176:    */
 177:   Object lookup(String name) throws NamingException;
 178: 
 179:   /**
 180:    * Give the specified name for the specified object. Unlike bind, this method
 181:    * silently replaces the existing binding for this name, if one exists.
 182:    * 
 183:    * @param name the name that will be given to the object (in the scope of this
 184:    *          context).
 185:    * @param obj the object being named.
 186:    * @throws InvalidAttributesException if the object does not supply all
 187:    *           required attributes.
 188:    * @throws NamingException if the naming operation has failed due other
 189:    *           reasons.
 190:    */
 191:   void rebind(Name name, Object obj) throws NamingException;
 192: 
 193:   /**
 194:    * Give the specified name for the specified object. Unlike bind, this method
 195:    * silently replaces the existing binding for this name, if one exists.
 196:    * 
 197:    * @param name the name that will be given to the object (in the scope of this
 198:    *          context).
 199:    * @param obj the object being named.
 200:    * @throws InvalidAttributesException if the object does not supply all
 201:    *           required attributes.
 202:    * @throws NamingException if the naming operation has failed due other
 203:    *           reasons.
 204:    */
 205:   void rebind(String name, Object obj) throws NamingException;
 206: 
 207:   /**
 208:    * Removes the name - object mapping from the current context. This method
 209:    * returns without action if the name is not bound to an object in the
 210:    * terminal context, but throws {@link NameNotFoundException} if one of the
 211:    * intermadiate contexts does not exist.
 212:    * 
 213:    * @param name the name to be removed
 214:    * @throws NameNotFoundException if one of the intermediate naming contexts
 215:    *           does not exist. Will not be thrown if just the terminal binding
 216:    *           is missing.
 217:    * @throws NamingException if the naming operation has failed due other
 218:    *           reasons.
 219:    */
 220:   void unbind(Name name) throws NamingException;
 221: 
 222:   /**
 223:    * Removes the name - object mapping from the current context. This method
 224:    * returns without action if the name is not bound to an object in the
 225:    * terminal context, but throws {@link NameNotFoundException} if one of the
 226:    * intermadiate contexts does not exist.
 227:    * 
 228:    * @param name the name to be removed
 229:    * @throws NameNotFoundException if one of the intermediate naming contexts
 230:    *           does not exist. Will not be thrown if just the terminal binding
 231:    *           is missing.
 232:    * @throws NamingException if the naming operation has failed due other
 233:    *           reasons.
 234:    */
 235:   void unbind(String name) throws NamingException;
 236: 
 237:   /**
 238:    * Renames the existing binding, removing the existing and giving the new name
 239:    * for the same object.
 240:    * 
 241:    * @param oldName the existing name of the known object
 242:    * @param newName the new name of the same object
 243:    * @throws NameNotFoundException if the oldName is unknown for this context
 244:    * @throws NamingException if the naming operation has failed due other
 245:    *           reasons.
 246:    */
 247:   void rename(Name oldName, Name newName) throws NamingException;
 248: 
 249:   /**
 250:    * Renames the existing binding, removing the existing and giving the new name
 251:    * for the same object.
 252:    * 
 253:    * @param oldName the existing name of the known object
 254:    * @param newName the new name of the same object
 255:    * @throws NameNotFoundException if the oldName is unknown for this context
 256:    * @throws NamingException if the naming operation has failed due other
 257:    *           reasons.
 258:    */
 259:   void rename(String oldName, String newName) throws NamingException;
 260: 
 261:   /**
 262:    * Creates and returns the enumeration over the name bindings that are present
 263:    * the given subcontext. The enumeration elements have the type of
 264:    * {@link NameClassPair}, providing also information about the class of the
 265:    * bound object. The behaviour in the case if the bindings are added or
 266:    * removed later is not defined. The contents of the subcontexts are not
 267:    * included.
 268:    * 
 269:    * @param name the name of the subcontext
 270:    * @return the enumeration over the names, known for the given subcontext.
 271:    * @throws NamingException
 272:    */
 273:   NamingEnumeration<NameClassPair> list(Name name) throws NamingException;
 274: 
 275:   /**
 276:    * Creates and returns the enumeration over the name bindings that are present
 277:    * the given subcontext. The enumeration elements have the type of
 278:    * {@link NameClassPair}, providing also information about the class of the
 279:    * bound object. The behaviour in the case if the bindings are added or
 280:    * removed later is not defined. The contents of the subcontexts are not
 281:    * included.
 282:    * 
 283:    * @param name the name of the subcontext
 284:    * @return the enumeration over the names, known for the given subcontext.
 285:    * @throws NamingException
 286:    */
 287:   NamingEnumeration<NameClassPair> list(String name) throws NamingException;
 288: 
 289:   /**
 290:    * Creates and returns the enumeration over the name - object bindings that
 291:    * are present the given subcontext. The enumeration elements have the type of
 292:    * {@link Binding}, providing also information about the class of the bound
 293:    * object. The behaviour in the case if the bindings are added or removed
 294:    * later is not defined. The contents of the subcontexts are not included.
 295:    * 
 296:    * @param name the name of the subcontext
 297:    * @return the enumeration over the names, known for the given subcontext.
 298:    * @throws NamingException
 299:    */
 300:   NamingEnumeration<Binding> listBindings(Name name) throws NamingException;
 301: 
 302:   /**
 303:    * Creates and returns the enumeration over the name - object bindings that
 304:    * are present the given subcontext. The enumeration elements have the type of
 305:    * {@link Binding}, providing also information about the class of the bound
 306:    * object. The behaviour in the case if the bindings are added or removed
 307:    * later is not defined. The contents of the subcontexts are not included.
 308:    * 
 309:    * @param name the name of the subcontext
 310:    * @return the enumeration over the names, known for the given subcontext.
 311:    * @throws NamingException
 312:    */
 313:   NamingEnumeration<Binding> listBindings(String name) throws NamingException;
 314: 
 315:   /**
 316:    * Creates the new naming subcontext and binds it to the current (this)
 317:    * context.
 318:    * 
 319:    * @param name the name of the new context being created
 320:    * @return the newly created context, bound to the instance of the context on
 321:    *         that the method has been called
 322:    * @throws NameAlreadyBoundException if this name is already bound
 323:    * @throws InvalidAttributesException if the creation of the new context
 324:    *           requires the missing mandatory attributes
 325:    * @throws NamingException
 326:    */
 327:   Context createSubcontext(Name name) throws NamingException;
 328: 
 329:   /**
 330:    * Creates the new naming subcontext and binds it to the current (this)
 331:    * context.
 332:    * 
 333:    * @param name the name of the new context being created
 334:    * @return the newly created context, bound to the instance of the context on
 335:    *         that the method has been called
 336:    * @throws NameAlreadyBoundException if this name is already bound
 337:    * @throws InvalidAttributesException if the creation of the new context
 338:    *           requires the missing mandatory attributes
 339:    * @throws NamingException
 340:    */
 341:   Context createSubcontext(String name) throws NamingException;
 342: 
 343:   /**
 344:    * Removes the naming subcontext from this naming context. Returns without
 345:    * action if such subcontext does not exist. The context being destroyed must
 346:    * be empty.
 347:    * 
 348:    * @param name the name of the subcontext beig removed.
 349:    * @throws ContextNotEmptyException if the named context is not empty.
 350:    * @throws NamingException
 351:    */
 352:   void destroySubcontext(Name name) throws NamingException;
 353: 
 354:   /**
 355:    * Removes the naming subcontext from this naming context. Returns without
 356:    * action if such subcontext does not exist. The context being destroyed must
 357:    * be empty.
 358:    * 
 359:    * @param name the name of the subcontext beig removed.
 360:    * @throws ContextNotEmptyException if the named context is not empty.
 361:    * @throws NamingException
 362:    */
 363:   void destroySubcontext(String name) throws NamingException;
 364:  
 365:   /**
 366:    * Retrieves the named object, not following the link of the terminal atomic
 367:    * component of the name. If the object, named by the passed name, is not a
 368:    * link, returns that object itself. The intermediate links, if present, are
 369:    * followed.
 370:    * 
 371:    * @param name the name of the object that may be a link, leading to another
 372:    *          object.
 373:    * @return the named object, not following the terminal link (if present).
 374:    * @throws NamingException
 375:    */
 376:   Object lookupLink(Name name) throws NamingException;
 377: 
 378:   /**
 379:    * Retrieves the named object, not following the link of the terminal atomic
 380:    * component of the name. If the object, named by the passed name, is not a
 381:    * link, returns that object itself. The intermediate links, if present, are
 382:    * followed.
 383:    * 
 384:    * @param name the name of the object that may be a link, leading to another
 385:    *          object.
 386:    * @return the named object, not following the terminal link (if present).
 387:    * @throws NamingException
 388:    */
 389:   Object lookupLink(String name) throws NamingException;
 390:   
 391:   /**
 392:    * Obtains the name parser for parsing the names of the given naming
 393:    * subcontext.
 394:    * 
 395:    * @param name the name of the subcontext for that the parser must be obtained
 396:    * @return the parser to parse the names of that context
 397:    * @throws NamingException
 398:    */
 399:   NameParser getNameParser(Name name) throws NamingException;
 400: 
 401:   /**
 402:    * Obtains the name parser for parsing the names of the given naming
 403:    * subcontext.
 404:    * 
 405:    * @param name the name of the subcontext for that the parser must be obtained
 406:    * @return the parser to parse the names of that context
 407:    * @throws NamingException
 408:    */
 409:   NameParser getNameParser(String name) throws NamingException;
 410:   
 411:   /**
 412:    * Composes the name of this context together with another name, related to
 413:    * this context.
 414:    * 
 415:    * @param name a name, defined in the scope of this context
 416:    * @param prefix a name of this context itself, defined in the scope of some
 417:    *          ancestor
 418:    * @return the name of the same object as named by the first parameter, but
 419:    *         related to the context of the specified ancestor.
 420:    * @throws NamingException
 421:    */
 422:   Name composeName(Name name, Name prefix) throws NamingException;
 423: 
 424:   /**
 425:    * Composes the name of this context together with another name, related to
 426:    * this context.
 427:    * 
 428:    * @param name a name, defined in the scope of this context
 429:    * @param prefix a name of this context itself, defined in the scope of some
 430:    *          ancestor
 431:    * @return the name of the same object as named by the first parameter, but
 432:    *         related to the context of the specified ancestor.
 433:    * @throws NamingException
 434:    */
 435:   String composeName(String name, String prefix) throws NamingException;
 436:   
 437:   /**
 438:    * Add new environment property to the environment of this context. Both name
 439:    * and value of the new property must not be null. If the property is already
 440:    * defined, is current value is replaced by the propVal.
 441:    * 
 442:    * @param propName the name of the new property
 443:    * @param propVal the value of the new property
 444:    * @return the previous value of this property or null if the property has not
 445:    *         been previously defined
 446:    * @throws NamingException
 447:    */
 448:   Object addToEnvironment(String propName, Object propVal)
 449:       throws NamingException;
 450:   
 451:   /**
 452:    * Removes the property with the given name from the environment. Returns
 453:    * without action if this property is not defined.
 454:    * 
 455:    * @param propName the name of the property being removed.
 456:    * @return the value of the property that has been removed or null if the
 457:    *         property was not defined.
 458:    * @throws NamingException
 459:    */
 460:   Object removeFromEnvironment(String propName) throws NamingException;
 461:   
 462:   /**
 463:    * Returns the environment, associated with this naming context. The returned
 464:    * table should never be modified by the caller. Use {@link #addToEnvironment}
 465:    * and {@link #removeFromEnvironment} to modify the environement, if needed.
 466:    * 
 467:    * @return the table, representing the environment of this context
 468:    * @throws NamingException
 469:    */
 470:   Hashtable<?,?> getEnvironment() throws NamingException;
 471:   
 472:   /**
 473:    * Releases all resources, associated with this context. The close() method
 474:    * can be called several times, but after it has been once invoked, it is not
 475:    * allowed to call any other method of this context,
 476:    * 
 477:    * @throws NamingException
 478:    */
 479:   void close() throws NamingException;
 480: 
 481:   /**
 482:    * Returs the full name of this naming context. The returned string is not a
 483:    * JNDI composite name and should not be passed directly to the methods of the
 484:    * naming context.
 485:    * 
 486:    * @return the full name of this naming context, in its own namespace.
 487:    * @throws OperationNotSupportedException if the naming system, represented by
 488:    *           this context, does not support the notation of the full name.
 489:    * @throws NamingException
 490:    */
 491:   String getNameInNamespace() throws NamingException;
 492: }