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 */ bind(Name name, Object obj)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 */ bind(String name, Object obj)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 */ lookup(Name name)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 */ lookup(String name)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 */ rebind(Name name, Object obj)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 */ rebind(String name, Object obj)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 */ unbind(Name name)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 */ unbind(String name)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 */ rename(Name oldName, Name newName)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 */ rename(String oldName, String newName)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 */ list(Name name)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 */ list(String name)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 */ listBindings(Name name)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 */ listBindings(String name)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 */ createSubcontext(Name name)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 */ createSubcontext(String name)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 */ destroySubcontext(Name name)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 */ destroySubcontext(String name)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 */ lookupLink(Name name)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 */ lookupLink(String name)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 */ getNameParser(Name name)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 */ getNameParser(String name)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 */ composeName(Name name, Name prefix)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 */ composeName(String name, String prefix)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 */ addToEnvironment(String propName, Object propVal)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 */ removeFromEnvironment(String propName)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 */ getEnvironment()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 */ close()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 */ getNameInNamespace()491 String getNameInNamespace() throws NamingException; 492 } 493