| Frames | No Frames |
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: }