jdk-sandbox: src/java.naming/share/classes/javax/naming/package.html@e0efb29609bd (annotated)

2 90ce3da70b43 Initial load duke parents: diff changeset	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
90ce3da70b43 Initial load duke parents: diff changeset	2	<html>
90ce3da70b43 Initial load duke parents: diff changeset	3	<head>
90ce3da70b43 Initial load duke parents: diff changeset	4	<!--
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	5	Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
2 90ce3da70b43 Initial load duke parents: diff changeset	6	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load duke parents: diff changeset	7
90ce3da70b43 Initial load duke parents: diff changeset	8	This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load duke parents: diff changeset	9	under the terms of the GNU General Public License version 2 only, as
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	10	published by the Free Software Foundation. Oracle designates this
2 90ce3da70b43 Initial load duke parents: diff changeset	11	particular file as subject to the "Classpath" exception as provided
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 2 diff changeset	12	by Oracle in the LICENSE file that accompanied this code.
2 90ce3da70b43 Initial load duke parents: diff changeset	13
90ce3da70b43 Initial load duke parents: diff changeset	14	This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load duke parents: diff changeset	15	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load duke parents: diff changeset	16	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
90ce3da70b43 Initial load duke parents: diff changeset	17	version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load duke parents: diff changeset	18	accompanied this code).
90ce3da70b43 Initial load duke parents: diff changeset	19
90ce3da70b43 Initial load duke parents: diff changeset	20	You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load duke parents: diff changeset	21	2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load duke parents: diff changeset	22	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load duke parents: diff changeset	23
5551 327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc. ohair parents: 5506 diff changeset	24	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc. ohair parents: 5506 diff changeset	25	or visit www.oracle.com if you need additional information or have any
327690766109 6956202: Fix a few missed rebranding issues, please contact lines etc. ohair parents: 5506 diff changeset	26	questions.
2 90ce3da70b43 Initial load duke parents: diff changeset	27	-->
90ce3da70b43 Initial load duke parents: diff changeset	28	</head>
90ce3da70b43 Initial load duke parents: diff changeset	29	<body bgcolor="white">
90ce3da70b43 Initial load duke parents: diff changeset	30
90ce3da70b43 Initial load duke parents: diff changeset	31	Provides the classes and interfaces for accessing naming services.
90ce3da70b43 Initial load duke parents: diff changeset	32
90ce3da70b43 Initial load duke parents: diff changeset	33	<p>
90ce3da70b43 Initial load duke parents: diff changeset	34	This package defines the naming operations of the Java Naming and
30678 a8b7fd8ede97 8075284: fix up miscellaneous TM constructions darcy parents: 25859 diff changeset	35	Directory Interface™ (JNDI).
2 90ce3da70b43 Initial load duke parents: diff changeset	36	JNDI provides naming and directory functionality to applications
90ce3da70b43 Initial load duke parents: diff changeset	37	written in the Java programming language. It is designed to be
90ce3da70b43 Initial load duke parents: diff changeset	38	independent of any specific naming or directory service
90ce3da70b43 Initial load duke parents: diff changeset	39	implementation. Thus a variety of services--new, emerging, and
90ce3da70b43 Initial load duke parents: diff changeset	40	already deployed ones--can be accessed in a common way.
90ce3da70b43 Initial load duke parents: diff changeset	41
90ce3da70b43 Initial load duke parents: diff changeset	42
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	43	<h2>Context</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	44	<p>
90ce3da70b43 Initial load duke parents: diff changeset	45	This package defines the notion of a <em>context</em>, represented
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	46	by the <code>Context</code> interface.
2 90ce3da70b43 Initial load duke parents: diff changeset	47	A context consists of a set of name-to-object <em>bindings</em>.
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	48	<code>Context</code> is the core interface for looking up, binding, unbinding,
2 90ce3da70b43 Initial load duke parents: diff changeset	49	and renaming objects, and for creating and destroying subcontexts.
90ce3da70b43 Initial load duke parents: diff changeset	50	<p>
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	51	<code>lookup()</code> is the most commonly used operation.
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	52	You supply <code>lookup()</code>
2 90ce3da70b43 Initial load duke parents: diff changeset	53	the name of the object you want
90ce3da70b43 Initial load duke parents: diff changeset	54	to look up, and it returns the object bound to that name.
90ce3da70b43 Initial load duke parents: diff changeset	55	For example, the following code fragment looks up
90ce3da70b43 Initial load duke parents: diff changeset	56	a printer and sends a document to the printer object
90ce3da70b43 Initial load duke parents: diff changeset	57	to be printed:
90ce3da70b43 Initial load duke parents: diff changeset	58
90ce3da70b43 Initial load duke parents: diff changeset	59	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	60	<pre>
90ce3da70b43 Initial load duke parents: diff changeset	61	Printer printer = (Printer)ctx.lookup("treekiller");
90ce3da70b43 Initial load duke parents: diff changeset	62	printer.print(report);
90ce3da70b43 Initial load duke parents: diff changeset	63	</pre>
90ce3da70b43 Initial load duke parents: diff changeset	64	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	65
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	66	<h2>Names</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	67	<p>
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	68	Every naming method in the <code>Context</code>
2 90ce3da70b43 Initial load duke parents: diff changeset	69	interface has two
90ce3da70b43 Initial load duke parents: diff changeset	70	overloads: one that accepts a
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	71	<code>Name</code> argument and one that accepts a string name.
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	72	<code>Name</code> is an interface that represents a generic
2 90ce3da70b43 Initial load duke parents: diff changeset	73	name--an ordered sequence of zero of more components.
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	74	For these methods, <code>Name</code> can be used to represent a
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	75	<em>composite name</em> (<code>CompositeName</code>)
2 90ce3da70b43 Initial load duke parents: diff changeset	76	so that you can name an object using a name which spans multiple namespaces.
90ce3da70b43 Initial load duke parents: diff changeset	77	<p>
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	78	The overloads that accept <code>Name</code>
2 90ce3da70b43 Initial load duke parents: diff changeset	79	are useful for applications that need to manipulate names: composing
90ce3da70b43 Initial load duke parents: diff changeset	80	them, comparing components, and so on.
90ce3da70b43 Initial load duke parents: diff changeset	81	The overloads that accept string names are likely to be more useful
90ce3da70b43 Initial load duke parents: diff changeset	82	for simple applications, such as those that simply read in a name
90ce3da70b43 Initial load duke parents: diff changeset	83	and look up the corresponding object.
90ce3da70b43 Initial load duke parents: diff changeset	84
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	85	<h2>Bindings</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	86
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	87	The <code>Binding</code> class represents a name-to-object binding.
2 90ce3da70b43 Initial load duke parents: diff changeset	88	It is a tuple containing the name of the bound object,
90ce3da70b43 Initial load duke parents: diff changeset	89	the name of the object's class, and the object itself.
90ce3da70b43 Initial load duke parents: diff changeset	90	<p>
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	91	The <code>Binding</code> class is actually a subclass of
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	92	<code>NameClassPair</code>, which consists
2 90ce3da70b43 Initial load duke parents: diff changeset	93	simply of the object's name and the object's class name.
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	94	The <code>NameClassPair</code> is useful when you only want
2 90ce3da70b43 Initial load duke parents: diff changeset	95	information about the object's class and do not want to
90ce3da70b43 Initial load duke parents: diff changeset	96	pay the extra cost of getting the object.
90ce3da70b43 Initial load duke parents: diff changeset	97
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	98	<h2>References</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	99	Objects are stored in naming and directory services in different ways.
90ce3da70b43 Initial load duke parents: diff changeset	100	If an object store supports storing Java objects,
90ce3da70b43 Initial load duke parents: diff changeset	101	it might support storing an object in its serialized form.
90ce3da70b43 Initial load duke parents: diff changeset	102	However, some naming and directory services do not support the
90ce3da70b43 Initial load duke parents: diff changeset	103	storing of Java objects. Furthermore, for some
90ce3da70b43 Initial load duke parents: diff changeset	104	objects in the directory, Java programs are but one group of applications
90ce3da70b43 Initial load duke parents: diff changeset	105	that access them. In this case, a serialized Java object might
90ce3da70b43 Initial load duke parents: diff changeset	106	not be the most appropriate representation.
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	107	JNDI defines a <em>reference</em>, represented by the <code>Reference</code>
2 90ce3da70b43 Initial load duke parents: diff changeset	108	class, which contains information on how to construct a copy of the object.
90ce3da70b43 Initial load duke parents: diff changeset	109	JNDI will attempt to turn references looked up from the directory
90ce3da70b43 Initial load duke parents: diff changeset	110	into the Java objects they represent, so that
90ce3da70b43 Initial load duke parents: diff changeset	111	JNDI clients have the illusion that what
90ce3da70b43 Initial load duke parents: diff changeset	112	is stored in the directory are Java objects.
90ce3da70b43 Initial load duke parents: diff changeset	113
90ce3da70b43 Initial load duke parents: diff changeset	114
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	115	<h2>The Initial Context</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	116
90ce3da70b43 Initial load duke parents: diff changeset	117	In JNDI, all naming and directory operations are performed relative
90ce3da70b43 Initial load duke parents: diff changeset	118	to a context. There are no absolute roots.
90ce3da70b43 Initial load duke parents: diff changeset	119	Therefore JNDI defines an <em>initial context</em>,
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	120	<code>InitialContext</code>,
2 90ce3da70b43 Initial load duke parents: diff changeset	121	which provides a starting point for naming and directory operations.
90ce3da70b43 Initial load duke parents: diff changeset	122	Once you have an initial context, you can use it to
90ce3da70b43 Initial load duke parents: diff changeset	123	look up other contexts and objects.
90ce3da70b43 Initial load duke parents: diff changeset	124
55131 9889f5e3ba00 8225129: Fix minor HTML issues in java.naming jjg parents: 47216 diff changeset	125	<h2>Exceptions</h2>
2 90ce3da70b43 Initial load duke parents: diff changeset	126
90ce3da70b43 Initial load duke parents: diff changeset	127	JNDI defines a class hierarchy for exceptions that can be thrown in
90ce3da70b43 Initial load duke parents: diff changeset	128	the course of performing naming and directory operations. The root of
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	129	this class hierarchy is <code>NamingException</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	130	Programs interested in dealing with a particular exception
90ce3da70b43 Initial load duke parents: diff changeset	131	can catch the corresponding subclass of the exception.
32029 a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming avstepan parents: 30678 diff changeset	132	Otherwise, programs should catch <code>NamingException</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	133
90ce3da70b43 Initial load duke parents: diff changeset	134
90ce3da70b43 Initial load duke parents: diff changeset	135	<h2>Package Specification</h2>
90ce3da70b43 Initial load duke parents: diff changeset	136
90ce3da70b43 Initial load duke parents: diff changeset	137	The JNDI API Specification and related documents can be found in the
45136 bd5c526bc443 8180176: Broken javadoc links in java.logging and java.naming dfuchs parents: 45132 diff changeset	138	{@extLink jndi_overview JNDI documentation}.
2 90ce3da70b43 Initial load duke parents: diff changeset	139
90ce3da70b43 Initial load duke parents: diff changeset	140	@since 1.3
90ce3da70b43 Initial load duke parents: diff changeset	141
90ce3da70b43 Initial load duke parents: diff changeset	142	</body>
90ce3da70b43 Initial load duke parents: diff changeset	143	</html>

author	herrick
	Tue, 24 Sep 2019 13:41:16 -0400
branch	JDK-8200758-branch
changeset 58301	e0efb29609bd
parent 55131	9889f5e3ba00
permissions	-rw-r--r--