JNDI API Tutorial and Reference... | Buy

How to Use This Book

This book teaches you how to write directory-enabled Java™ applications by using the Java Naming and Directory Interface™ (JNDI). It is divided into two parts: a tutorial and a reference.

It is intended as a tutorial and reference only for the JNDI and not for the rest of the Java Platform. For a tutorial-style presentation of the class libraries in the rest of the Java Platform, see The Jav™ Tutorial and The JFC Swing Tutorial, by Mary Campione and Kathy Walrath, and The Java™ Tutorial Continued, by Mary Campione, Kathy Walrath, Allison Huml, and the Tutorial team. For a reference-style presentation of the class libraries in other parts of the Java Platform, see The Java™ Class Libraries books by Patrick Chan, Rosanna Lee, and Douglas Kramer. This book also does not explain any part of the Java programming language. Several books are available for learning the language. These include The Java™ Programming Language, by Ken Arnold and James Gosling, and The Java™ Language Specification, by James Gosling, Bill Joy, and Guy Steele.

Following is an overview of this book.

Tutorial

The first part of this book is a tutorial. It is modeled after The Java Tutorial, by Mary Campione and Kathy Walrath.

Trails and Lessons

The tutorial consists of six trails-programming lessons grouped together by topic. To learn about a certain topic, go to the Table of Contents, decide which trail meets your needs, and go through the lessons in that trail. For example, if you are interested in writing a service provider, select the Building a Service Provider trail.

You can read the tutorial sequentially or select trails in any order. However, some of the beginner trails are prerequisites for the more advanced trails.

The first page of a trail contains a high-level overview of the trail. It lists, describes, and provides references to all of the lessons on the trail. It also provides a detailed table of contents of the lessons in the trail.

Each lesson begins with an introduction to the material in the lesson. Most lessons contain many examples. Trying the examples as you go along will help you to understand the concepts discussed in each lesson.

Links

The online version of this tutorial is filled with hyperlinks to sections inside and outside of the tutorial. In this hardcopy version of the tutorial, these hyperlinks have been handled as follows.

A link to a section, lesson, or trail within the tutorial is replaced by a cross reference, annotated by a page number.
A link to a method, class, interface, or package in the JNDI has been removed. Use instead the reference part of this book to look up the item.
A link to an Internet RFC or Internet-draft has been removed. These documents may be accessed both from the CD that accompanies this book and the Web site at http://www.ietf.org.
A link to an external document or software has been replaced by the item's URL. These files may also be found on the accompanying CD.
A link to a sample program or configuration file has been removed. Simply find the file on the accompanying CD (see later in this Preface for instructions).

Examples

All of the code examples in the tutorial have been compiled and run by using the following software.

The FCS version of the Java™ 2 SDK, Standard Edition, v1.2 on either Solaris or Windows NT or both
The 1.2.1 version of the JNDI class libraries
The 1.2.2 version of the LDAP service provider
The 1.2 Beta 2 version of the file system service provider

Most of the complete examples are available both online from the JNDI Web site ( http://java.sun.com/products/jndi/tutorial ) and on the accompanying CD. This tutorial is located in the Tutorials/jndi directory on the CD. Each trail resides in its own directory, under which are located subdirectories for each lesson within the trail. The examples and related files used in a lesson are found in the src subdirectory of the lesson's directory. For example, the examples in the Naming Operations lesson in The Basics trail are found in the Tutorials/jndi/basics/naming/src directory. Tools and utilities for configuring the examples are found in the directories Tutorials/jndi/config/fs and Tutorials/jndi/config/LDAP.

We strongly encourage you to try the examples that accompany this tutorial as you go along. To do that, you will need the JNDI classes and a v1.1.2 or higher version of the Java Platform software, such as the JDK software ( http://java.sun.com/products/jdk ). The JDK provides a compiler that you can use to compile Java programs. It also provides an interpreter for running Java applications. To run Java applets, you can use the JDK Applet Viewer or any Java-compatible Web browser, such as the HotJava™ browser.

Online Version

The complete online tutorial is available both on the accompanying CD and from the JNDI Web site. The title page of each lesson contains a URL for the corresponding lesson online.

Reference

The second part of this book is a reference. Its format is similar to a dictionary's in that it is designed to optimize the time that it takes for you to look up information about a class or class member.

Package Overviews

The package overviews briefly describe each package and its classes. Each overview includes a general description about the package, as well as diagrams that show the inheritance hierarchy of its classes.

Alphabetical Reference of Classes

This part covers the alphabetical listing of the classes from the following five packages:

javax.naming
 javax.naming.directory
 javax.naming.event
 javax.naming.ldap
 javax.naming.spi

The classes are ordered alphabetically without regard to package. Each is described in its own chapter that contains a picture of the class hierarchy, a class description, a member summary, and descriptions for each member. Most examples for the class or items within the class are found in the tutorial part of this book.

Class Hierarchy Diagram

Each chapter starts with a class diagram like that shown in Figure i. This diagram shows all of the ancestors of the class, its siblings, its immediate descendents, and any interfaces that it implements. In these diagrams, if a package name precedes a class or interface name, then the class or interface is not in the same package as the current class.

In the diagrams, the different kinds of Java entities are distinguished visually as follows:

The interface: A rounded rectangle
The class: A rectangle
The abstract class: A rectangle with an empty dot
The final class: A rectangle with a black dot
Classes with subclasses: A rectangle with a small black triangle in the lower-right corner

The class or interface being described in the current chapter is shaded grey. A solid line represents extends and a dotted line represents implements.

Class Description

In the class description, we describe all of the properties of the class. For example, the discussion of the properties of the Context interface includes information on how names and environment properties are treated. Describing in one place all of a class's ava

Rosanna Lee is a Senior Staff Engineer at Sun Microsystems, Inc.

List of Figures

xiii

List of Tables

xv

Preface

xvii

Tutorial

1

(2)

Getting Started

3

(34)

Naming and Directory Concepts

7

(10)

JNDI Overview

17

(8)

Examples

25

(6)

Common Problems (and Their Solutions)

31

(6)

The Basics

37

(38)

Preparations

41

(12)

Naming Operations

53

(6)

Directory Operations

59

(16)

Beyond the Basics

75

(76)

What's in a Name?

79

(16)

Environment Properties

95

(16)

Event Notification

111

(12)

URLs

123

(8)

Federation

131

(8)

Miscellaneous

139

(12)

Java Objects in the Directory

151

(50)

Storing Objects in the Directory

155

(16)

State Factories

171

(8)

Reading Objects from the Directory

179

(6)

Object Factories

185

(10)

Rrpresentation in the Directory

195

(6)

Tips for LDAP Users

201

(110)

Comparison of the LDAP and JNDI Models

207

(14)

Security

221

(16)

Miscellaneous

237

(12)

Searches

249

(10)

Referrals

259

(12)

Schema

271

(18)

Controls and Extensions

289

(16)

Frequently Asked Questions

305

(6)

Building a Service Provider

311

(86)

The Big Picture

315

(6)

The Ground Rules

321

(10)

The Essential Components

331

(14)

Adding Directory Support

345

(12)

Adding URL Support

357

(14)

Adding Federation Support

371

(16)

Miscellaneous

387

(10)

Class Libraries Reference

397

(360)

Package Overviews

javax.naming

399

(6)

javax.naming.directory

405

(3)

javax.naming.event

408

(2)

javax.naming.ldap

410

(3)

javax.naming.spi

413

(4)

Alphabetical Reference of Classes

Attribute

417

(8)

AttributeInUseException

425

(2)

AttributeModificationException

427

(3)

Attributes

430

(4)

AuthenticationException

434

(2)

AuthenticationNotSupportedException

436

(2)

BasicAttribute

438

(10)

BasicAttributes

448

(6)

BinaryRefAddr

454

(3)

Binding

457

(3)

CannotProceedException

460

(7)

CommunicationExpection

467

(2)

CompositeName

469

(11)

CompoundName

480

(12)

ConfigurationException

492

(2)

Context

494

(23)

ContextNotEmptyException

517

(2)

Control

519

(3)

ControlFactory

522

(4)

DirContext

526

(14)

DirectoryManager

540

(4)

DirObjectFactory

544

(3)

DirStateFactory

547

(3)

DirStateFactory.Result

550

(2)

EventContext

552

(5)

EventDirContext

557

(2)

ExtendedRequest

559

(4)

ExtendedResponse

563

(2)

HasControls

565

(2)

InitialContext

567

(13)

InitialContextFactory

580

(2)

InitialContextFactoryBuilder

582

(2)

InitialDirContext

584

(7)

InitialLdapContext

591

(2)

InsufficientResourcesException

593

(2)

InterruptedNamingException

595

(2)

InvalidAttributeIdentifierException

597

(2)

InvalidAttributesException

599

(2)

InvalidAttributeValueException

601

(2)

InvalidNameException

603

(2)

InvalidSearchControlsException

605

(2)

InvalidSearchFilterException

607

(2)

LdapContext

609

(8)

LdapReferralException

617

(3)

LimitExceededException

620

(2)

LinkException

622

(7)

LinkLoopException

629

(1)

LinkRef

630

(2)

MalformedLinkException

632

(1)

ModificationItem

633

(2)

Name

635

(7)

NameAlreadyBoundException

642

(2)

NameClassPair

644

(4)

NameNotFoundException

648

(2)

NameParser

650

(1)

NamespaceChangeListener

651

(2)

NamingEnumeration

653

(3)

NamingEvent

656

(7)

NamingException

663

(9)

NamingExceptionEvent

672

(2)

NamingListener

674

(2)

NamingManager

676

(9)

NamingSecurityException

685

(2)

NoInitialContextException

687

(2)

NoPermissionException

689

(2)

NoSuchAttributeException

691

(2)

NotContextException

693

(2)

ObjectChangeListener

695

(2)

ObjectFactory

697

(3)

ObjectFacotryBuilder

700

(2)

OperationNotSupportedException

702

(2)

PartialResultException

704

(2)

RefAddr

706

(3)

Reference

709

(7)

Referenceable

716

(1)

ReferralException

717

(5)

Resolver

722

(2)

ResolveResult

724

(4)

SchemaViolationException

728

(2)

SeachControls

730

(7)

SearchResult

737

(3)

ServiceUnavailableException

740

(2)

SizeLimitExceedeException

742

(2)

StateFactory

744

(3)

StringRefAddr

747

(2)

TimeLimitExceededException

749

(2)

UnsolicitedNotification

751

(2)

UnsolicitedNotificationEvent

753

(2)

UnsolicitedNotificationListener

755

(2)

Appendix: LDAP Schemas

757

(4)

Index

761

What is included with this book?

The New copy of this book will include any supplemental materials advertised. Please check the title of the book to determine if it should include any access cards, study guides, lab manuals, CDs, etc.

The Used, Rental and eBook copies of this book are not guaranteed to include any supplemental materials. Typically, only the book itself is included. This is true even if the title states it includes any access cards, study guides, lab manuals, CDs, etc.

How to Use This BookThis book teaches you how to write directory-enabled Java applications by using the Java Naming and Directory Interface (JNDI). It is divided into two parts: a tutorial and a reference.It is intended as a tutorial and reference only for the JNDI and not for the rest of the Java Platform. For a tutorial-style presentation of the class libraries in the rest of the Java Platform, seeThe Jav TutorialandThe JFC Swing Tutorial,by Mary Campione and Kathy Walrath, andThe Java Tutorial Continued,by Mary Campione, Kathy Walrath, Allison Huml, and the Tutorial team. For a reference-style presentation of the class libraries in other parts of the Java Platform, seeThe Java Class Librariesbooks by Patrick Chan, Rosanna Lee, and Douglas Kramer. This book also does not explain any part of the Java programming language. Several books are available for learning the language. These includeThe Java Programming Language,by Ken Arnold and James Gosling, andThe Java Language Specification,by James Gosling, Bill Joy, and Guy Steele.Following is an overview of this book. TutorialThe first part of this book is a tutorial. It is modeled afterThe Java Tutorial,by Mary Campione and Kathy Walrath. Trails and LessonsThe tutorial consists of six trails-programming lessons grouped together by topic. To learn about a certain topic, go to theTable of Contents, decide which trail meets your needs, and go through the lessons in that trail. For example, if you are interested in writing a service provider, select theBuilding a Service Providertrail.You can read the tutorial sequentially or select trails in any order. However, some of the beginner trails are prerequisites for the more advanced trails.The first page of a trail contains a high-level overview of the trail. It lists, describes, and provides references to all of the lessons on the trail. It also provides a detailed table of contents of the lessons in the trail.Each lesson begins with an introduction to the material in the lesson. Most lessons contain many examples. Trying the examples as you go along will help you to understand the concepts discussed in each lesson. LinksThe online version of this tutorial is filled with hyperlinks to sections inside and outside of the tutorial. In this hardcopy version of the tutorial, these hyperlinks have been handled as follows. A link to a section, lesson, or trail within the tutorial is replaced by a cross reference, annotated by a page number. A link to a method, class, interface, or package in the JNDI has been removed. Use instead the reference part of this book to look up the item. A link to an Internet RFC or Internet-draft has been removed. These documents may be accessed both from the CD that accompanies this book and the Web site at http://www.ietf.org . A link to an external document or software has been replaced by the item's URL. These files may also be found on the accompanying CD. A link to a sample program or configuration file has been removed. Simply find the file on the accompanying CD (see later in this Preface for instructions). ExamplesAll of the code examples in the tutorial have been compiled and run by using the following software. The FCS version of the Java 2 SDK, Standard Edition, v1.2 on either Solaris or Windows NT or both The 1.2.1 version of the JNDI class libraries The 1.2.2 version of the LDAP service provider The 1.2 Beta 2 version of the file system service providerMost of the complete examples are available both online from the JNDI Web site ( http://java.sun.com/products/jndi/tutorial