001/* Context.java -- A naming context 002 Copyright (C) 2000, 2006 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package javax.naming; 040 041import java.util.Hashtable; 042 043import javax.naming.directory.InvalidAttributesException; 044 045public interface Context 046{ 047 /** 048 * Property with name of the inital context factory to use 049 */ 050 String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"; 051 052 /** 053 * Property with colon-separated list of object factories to use. 054 */ 055 String OBJECT_FACTORIES = "java.naming.factory.object"; 056 057 /** 058 * Property with colon-separated list of state factories to use. 059 */ 060 String STATE_FACTORIES = "java.naming.factory.state"; 061 062 /** 063 * Property with colon-separated list of package prefixes to use. 064 */ 065 String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs"; 066 067 /** 068 * Property with URL specifying configuration for the service provider to use. 069 */ 070 String PROVIDER_URL = "java.naming.provider.url"; 071 072 /** 073 * Property with the DNS host and domain names to use. 074 */ 075 String DNS_URL = "java.naming.dns.url"; 076 077 /** 078 * Property with the authoritativeness of the service requested. 079 */ 080 String AUTHORITATIVE = "java.naming.authoritative"; 081 082 /** 083 * Property with the batch size to use when returning data via the service's 084 * protocol. 085 */ 086 String BATCHSIZE = "java.naming.batchsize"; 087 088 /** 089 * Property defining how referrals encountered by the service provider are to 090 * be processed. 091 */ 092 String REFERRAL = "java.naming.referral"; 093 094 /** 095 * Property specifying the security protocol to use. 096 */ 097 String SECURITY_PROTOCOL = "java.naming.security.protocol"; 098 099 /** 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}