Download the full version and explore a variety of ebooks

or textbooks at https://ebookmass.com

Practical Spring LDAP: Using Enterprise Java-Based

LDAP in Spring Data and Spring Framework 6 2nd
Edition Balaji Varanasi

_____ Follow the link below to get your download now _____

https://ebookmass.com/product/practical-spring-ldap-using-
enterprise-java-based-ldap-in-spring-data-and-spring-
framework-6-2nd-edition-balaji-varanasi/

Access ebookmass.com now to download high-quality

ebooks or textbooks
We have selected some products that you may be interested in
Click the link to download now or visit ebookmass.com
for more options!.

Practical Spring LDAP: Using Enterprise Java-Based LDAP in

Spring Data and Spring Framework 6 2nd Edition Varanasi
Balaji
https://ebookmass.com/product/practical-spring-ldap-using-enterprise-
java-based-ldap-in-spring-data-and-spring-framework-6-2nd-edition-
varanasi-balaji/

Pro Spring Security: Securing Spring Framework 6 and Boot

3–based Java Applications, Third Edition Massimo Nardone

https://ebookmass.com/product/pro-spring-security-securing-spring-
framework-6-and-boot-3-based-java-applications-third-edition-massimo-
nardone/

Beginning Spring Data: Data Access and Persistence for

Spring Framework 6 and Boot 3 Andres Sacco

https://ebookmass.com/product/beginning-spring-data-data-access-and-
persistence-for-spring-framework-6-and-boot-3-andres-sacco/

Pro Spring 6 with Kotlin: An In-depth Guide to Using

Kotlin APIs in Spring Framework 6 1st Edition Peter Späth

https://ebookmass.com/product/pro-spring-6-with-kotlin-an-in-depth-
guide-to-using-kotlin-apis-in-spring-framework-6-1st-edition-peter-
spath/
Spring 6 Recipes: A Problem-Solution Approach to Spring
Framework Marten Deinum

https://ebookmass.com/product/spring-6-recipes-a-problem-solution-
approach-to-spring-framework-marten-deinum/

Pro Spring 6: An In-Depth Guide to the Spring Framework,

6th Edition Iuliana Cosmina

https://ebookmass.com/product/pro-spring-6-an-in-depth-guide-to-the-
spring-framework-6th-edition-iuliana-cosmina/

Beginning Spring 6 Joseph B. Ottinger

https://ebookmass.com/product/beginning-spring-6-joseph-b-ottinger/

Hacking with Spring Boot 2.3: Reactive Edition

https://ebookmass.com/product/hacking-with-spring-boot-2-3-reactive-
edition/

Building Modern Business Applications: Reactive Cloud

Architecture for Java, Spring, and PostgreSQL 1st Edition
Peter Royal
https://ebookmass.com/product/building-modern-business-applications-
reactive-cloud-architecture-for-java-spring-and-postgresql-1st-
edition-peter-royal-2/
Balaji Varanasi and Andres Sacco

Practical Spring LDAP

Using Enterprise Java-Based LDAP in Spring Data
and Spring Framework 6
2nd ed.
Balaji Varanasi
Salt Lake City, UT, USA

Andres Sacco
Buenos Aires, Buenos Aires, Argentina

ISBN 979-8-8688-0001-6 e-ISBN 979-8-8688-0002-3

https://doi.org/10.1007/979-8-8688-0002-3

© Balaji Varanasi and Andres Sacco 2013, 2023

This work is subject to copyright. All rights are solely and exclusively
licensed by the Publisher, whether the whole or part of the material is
concerned, specifically the rights of translation, reprinting, reuse of
illustrations, recitation, broadcasting, reproduction on microfilms or in
any other physical way, and transmission or information storage and
retrieval, electronic adaptation, computer software, or by similar or
dissimilar methodology now known or hereafter developed.

The use of general descriptive names, registered names, trademarks,

service marks, etc. in this publication does not imply, even in the
absence of a specific statement, that such names are exempt from the
relevant protective laws and regulations and therefore free for general
use.

The publisher, the authors, and the editors are safe to assume that the
advice and information in this book are believed to be true and accurate
at the date of publication. Neither the publisher nor the authors or the
editors give a warranty, expressed or implied, with respect to the
material contained herein or for any errors or omissions that may have
been made. The publisher remains neutral with regard to jurisdictional
claims in published maps and institutional affiliations.
This Apress imprint is published by the registered company APress
Media, LLC, part of Springer Nature.
The registered company address is: 1 New York Plaza, New York, NY
10004, U.S.A.
To my grandparents who taught me the importance of learning new
things all the time.
To my wife and children for supporting me while writing this book.
Introduction
Practical Spring LDAP provides complete coverage of Spring LDAP, a
framework designed to take the pain out of LDAP programming. This
book starts by explaining the fundamental concepts of LDAP and
showing the reader how to set up the development environment. It
then dives into Spring LDAP, analyzing the problems it is designed to
solve. After that, the book focuses on the practical aspects of unit
testing and integration testing with LDAP. An in-depth treatment of
LDAP controls and Spring LDAP features, such as Object-Directory
Mapping and LDIF (LDAP Data Interchange Format) parsing, follows
this. Finally, it concludes with discussions on LDAP authentication and
connection pooling.
What the Book Covers
Chapter 1 starts with an overview of directory servers. It then discusses
the basics of LDAP and introduces the four LDAP information models. It
finishes with an introduction to the LDIF format used for representing
LDAP data.
Chapter 2 focuses on the Java Naming and Directory Interface
(JNDI). In this chapter, you look at creating applications that interact
with LDAP using plain JNDI.
Chapter 3 explains Spring LDAP and why it is an important option in
an enterprise developer’s repertoire. In this chapter, you set up the
development environment to create Spring LDAP applications and
other important tools, such as Maven and a test LDAP server. Finally,
you implement a basic but complete Spring LDAP application using
annotations.
Chapter 4 covers the fundamentals of unit and integration testing.
You then look at setting up an embedded LDAP server for unit testing
your application code; alternatively, you will see how to use
Testcontainers to run LDAP using a docker image. You also review
available tools for generating test data. Finally, you use the Mockito
library to mock test LDAP code.
Chapter 5 introduces the basics of JNDI object factories and uses
these factories for creating objects that are more meaningful to the
application. You then examine a complete Data Access Object (DAO)
layer implementation using Spring LDAP and object factories.
Chapter 6 covers LDAP search. This chapter begins with the
underlying ideas of LDAP search. I then introduce various Spring LDAP
filters that make LDAP searching easier. Finally, you look at creating a
custom search filter to address situations where the current set is
insufficient.
Chapter 7 provides an in-depth overview of LDAP controls that can
be used for extending LDAP server functionality. Then it moves on to
sorting and paging LDAP results using sort and page controls.
Chapter 8 deals with Object-Directory Mapping (ODM), a feature in
Spring LDAP. In this chapter, you look at bridging the gap between the
domain model and the directory server. You then re-implement the DAO
using ODM concepts.
 Chapter 9 introduces the important ideas of transactions and
transactional integrity before analyzing the transaction abstractions
provided by Spring Framework. Finally, it takes a look at Spring LDAP’s
compensating transaction support.
Chapter 10 starts with implementing authentication, the most
common operation against LDAP. It then deals with parsing LDIF files
using another feature introduced in Spring. I end the chapter by looking
at the connection pooling support provided by Spring LDAP.

Target Audience
Practical Spring LDAP is intended for developers interested in building
Java/JEE applications using LDAP. It also teaches techniques for
creating unit/integration tests for LDAP applications. The book
assumes basic familiarity with Spring Framework; prior exposure to
LDAP is helpful but optional. Developers already familiar with Spring
LDAP will find best practices and examples to help them get the most
out of the framework.

Prerequisites
You should install Java JDK1 21 or higher on your machine, Maven2 3.8.0
or higher, and some IDE. Some options for the IDE could be Eclipse,3
IntelliJ IDEA,4 Visual Studio Code,5 and others, but you can choose
which is the best for you.
To reduce the complexity of installing all LDAP vendors on your
machine, I recommend you install Docker6 and use it to run each LDAP.
The use and installation of Docker are outside the scope of this book,
but there are some tutorials7 or cheatsheet8 with the most common
commands.

Note If you don’t have it installed on your machine, you can check
Appendixes A, B, and C, which have information about installing the
different tools and loading the information on LDAP.
After installing all the tools, you must check if they are correctly
installed before reading the different chapters.
In the case of Java, you need to run the following command:

% java -version
openjdk 21 2023-09-19
OpenJDK Runtime Environment (build 21+35-2513)
OpenJDK 64-Bit Server VM (build 21+35-2513, mixed
mode, sharing)

After that, you need to check if the version of Maven is correct using
this command:

% mvn --version
Apache Maven 3.9.1
Maven home: /usr/share/maven

Last, if you want to check whether Docker runs correctly on your

machine, you can do that using the following command:

% docker --version
Docker version 24.0.2, build cb74dfc

Remember that I mentioned that Docker is optional. It’s only

recommended for reducing the complexity of installing LDAP vendors
on your machine.

Downloading Source Code

The source code for the examples in this book can be downloaded from
www.apress.com. For detailed information about locating this book’s
source code, visit www.apress.com/gp/services/source-
code. The code is organized by chapter and can be built using Maven.

Questions?
If you have any questions or suggestions, contact the author at
sacco.andres@gmail.com.
Any source code or other supplementary material referenced by the
author in this book is available to readers on GitHub
(https://github.com/Apress). For more detailed information, please
visit https://www.apress.com/gp/services/source-code.
Acknowledgments
I would like to thank my family members and friends for their
encouragement and support during the writing of this book:
My wife, Gisela, who was always patient when I spent long hours at
my computer desk working on this book
My little daughter, Francesca, who helped me relax while writing
each chapter
My baby, Allegra, who is the new family member and my inspiration
to write this book
My friends, German Canale and Julian Delley, who always trusted me
to write a book and supported me during tough times
Specially mentioning Manuel Jordan for guiding me in improving
the quality of the book.
My sincere thanks to the beautiful team at Apress for their support
during the publication of this book. Thanks to Shonmirin P.A. for
providing excellent support. Finally, thanks to Mark Powers and Melissa
Duffy for suggesting and allowing me to write a book. Also, I want to
mention the great job that Balaji Varanasi did with the first edition of
this book which gave the base to write the second edition.
Table of Contents
Chapter 1:​Introduction to LDAP
LDAP Overview
Directory vs.​Database
Information Model
Object Classes
Directory Schema
Naming Model
Functional Model
Security Model
LDIF Format
LDAP History
LDAP Vendors
Sample Application
Summary
Chapter 2:​Java Support for LDAP
LDAP Using JNDI
Connect to LDAP
LDAP Operations
Closing Resources
Creating a New Entry
Updating an Entry
Removing an Entry
Searching Entries
Check How the Operations Work
JNDI Drawbacks
 Summary
Chapter 3:​Introducing Spring LDAP
Motivation
Documentation and Source Code Spring LDAP
Spring LDAP Packaging
Installing Spring LDAP Using Maven
Spring LDAP Archetypes
Creating Projects Using IntelliJ
Spring LDAP Hello World
Spring ApplicationConte​xt
Spring-Powered Search Client
Spring LdapTemplate Operations
Add Operation
Modify Operation
Deleting Operation
Summary
Chapter 4:​Testing LDAP Code
Concepts About Testing
Unit Testing
Mock Testing
Integration Testing
Libraries to Do Tests
JUnit
Mockito
Testcontainers
Creating the Tests
 Mocking the Templates
Testing Using Embedded Server
Moving to Tests with Testcontainers
Summary
Chapter 5:​Advanced Spring LDAP
JNDI Object Factories
Spring and Object Factories
DAO Implementation Using Object Factory
Implementing Finder Methods
Create Method
Update Method
Delete Method
Summary
Chapter 6:​Searching LDAP
LDAP Search Criteria
Base Parameter
Scope Parameter
Filter Parameter
Optional Parameters
LDAP Injection
Spring LDAP Filters
EqualsFilter
LikeFilter
PresentFilter
NotPresentFilter​
Not Filter
 GreaterThanOrEqu​alsFilter
LessThanOrEquals​Filter
AndFilter
OrFilter
HardcodedFilter
WhitespaceWildca​rdsFilter
Handling Special Characters
LDAP Query Builder Parameters
Summary
Chapter 7:​Sorting and Paging Results
LDAP Controls
Identifying Supported Controls
JNDI and Controls
Spring LDAP and Controls
Sort Control
Implementing Custom DirContextProces​sor
Paged Search Controls
Summary
Chapter 8:​Object-Directory Mapping
Spring ODM Basics
ODM Metadata
ODM Service Class
Creating Custom Converter
Summary
Chapter 9:​LDAP Transactions
Transaction Basics
 Local vs.​Global Transactions
Programmatic vs.​Declarative Transactions
Programmatically​
Declaratively
Spring Transaction Abstraction
Declarative Transactions Using Spring
LDAP Transaction Support
Spring LDAP Transaction Support
Compensating Transactions
Summary
Chapter 10:​Odds and Ends
Authentication Using Spring LDAP
Handling Authentication Exceptions
Parsing LDIF Data
LDAP Connection Pooling
Built-In Connection Pooling
Spring LDAP Connection Pooling
Pool Validation
Summary
Appendix A:​Setting Up Environment Tools
Appendix B:​Recommended and Alternative Tools
Appendix C:​Set Up LDAP Server
Appendix D:​Opening a Project
Appendix E:​Further Reading
Index
About the Authors
Balaji Varanasi
is a software development manager and technology entrepreneur. He
has over 13 years of experience architecting and developing Java/.NET
applications and, more recently, iPhone apps. During this period, he has
worked in the areas of security, web accessibility, search, and
enterprise portals. He has a master’s degree in computer science and
serves as adjunct faculty, teaching programming and information
system courses. When not programming, he enjoys spending time with
his lovely wife in Salt Lake City, Utah.

Andres Sacco
has been working as a developer since
2007 in different languages, including
Java, PHP, Node.js, Scala, and Kotlin. His
background is mostly in Java and the
libraries or frameworks associated with
this language. At most of the companies
he worked for, he researched new
technologies to improve the
performance, stability, and quality of the
applications of each company. In 2017,
he started to find new ways to optimize
the transference of data between
applications to reduce the cost of
infrastructure. He suggested some
actions, some applicable in all of the manual microservices and others
in just a few. All of this work includes creating a series of theoretic-
practical projects (available on Manning.com). Recently, he coauthored
an Apress book titled Beginning Scala 3. He also published a set of
theoretic-practical projects about uncommon ways of testing, such as
architecture tests and chaos engineering.
About the Technical Reviewer
Manuel Jordan
is an autodidactic developer and researcher who enjoys learning new
technologies for his own experiments about creating new integrations
among them.
Manuel won the 2010 Springy Award – Community Champion and
Spring Champion 2013. In his little free time, he reads the Bible and
composes music on his bass and guitar.
You can reach him through his Twitter account, @dr_pompeii.
© The Author(s), under exclusive license to APress Media, LLC, part of Springer Nature 2023
B. Varanasi, A. Sacco, Practical Spring LDAP
https://doi.org/10.1007/979-8-8688-0002-3_1

1. Introduction to LDAP
Balaji Varanasi1 and Andres Sacco2
(1) Salt Lake City, UT, USA
(2) Buenos Aires, Buenos Aires, Argentina

We all deal with directories daily. We use a telephone directory to look up phone numbers. When visiting a
library, we use the library catalog to look up the books we want to read. We use the file system directory
with computers to store our files and documents. Simply put, a directory is a repository of information. The
information is usually organized so that it can be retrieved easily.
Directories on a network are typically accessed using the client/server communication model.
Applications wanting to read or write data to a directory communicate with specialized servers. The
directory server performs a read or write operation on the actual directory. Figure 1-1 shows this
client/server interaction.

Figure 1-1 Directory server and client interaction

The communication between the directory server and client applications is usually accomplished using
standardized protocols. The Lightweight Directory Access Protocol (LDAP) provides a standard protocol for
communicating with a directory. The directory servers that implement the LDAP protocol are usually called
LDAP servers. The LDAP protocol is based on an earlier X.5001 standard but is significantly simpler
(lightweight) and easily extensible. Over the years, the LDAP protocol went through iterations and is
currently at version 3.0.

LDAP Overview
LDAP defines a message protocol used by directory clients and directory servers. LDAP can be better
understood by considering the following four models it is based on:
The Information model determines the structure of information stored in the directory.
The Naming model defines how information is organized and identified in the directory.
The Functional model defines the operations performed on the directory.
The Security model defines how to protect information from unauthorized access.
We will look at each of these models in the following sections.

Directory vs. Database

Beginners often need clarification and picture an LDAP directory as a relational database. Like a database,
an LDAP directory stores information. However, several key characteristics set a directory apart from
relational databases.
LDAP directories typically store data that is relatively static. For example, employee information stored
in LDAP, such as their phone number or name, does not change daily. However, users and applications look
up this information very frequently. Since the data in a directory is accessed more often than updated, LDAP
directories follow the WORM principle2, 3 and are heavily optimized for read performance. Placing data that
change quite often in LDAP does not make sense.
Relational databases employ referential integrity and locking techniques to ensure data consistency. The
type of data stored in LDAP usually does not warrant such strict consistency requirements. Hence, most of
these features need to be present on LDAP servers. Also, transactional semantics to roll back transactions
are not defined under LDAP specification.
Relational databases follow normalization principles to avoid data duplication and redundancy. On the
other hand, LDAP directories are organized in a hierarchical, object-oriented way. This organization violates
some of the normalization principles. Also, there needs to be a concept of table joins in LDAP.
Even though directories lack several of the RDBMS4 features mentioned earlier, many modern LDAP
directories are built on top of relational databases such as DB2,5 MySQL,6 and PostgreSQL.7
At some point, LDAP has similar characteristics to nonrelational databases like Cassandra,8 MongoDB,9
and many others where the performance of the write/read, high availability, and scalability are more
relevant than the consistency.

Information Model
The basic unit of information stored in LDAP is an entry. Entries hold information about real-world objects
such as employees, servers, printers, and organizations. Each entry in an LDAP directory comprises zero or
more attributes. Attributes are key-value pairs that hold information about the object the entry represents.
The key portion of an attribute is also called the attribute type and describes the information that can be
stored in the attribute. The value portion of the attribute contains the actual information. Table 1-1 shows a
portion of an entry representing an employee. The left column in the entry contains the attribute types, and
the right column holds the attribute values.

Table 1-1 Employee LDAP Entry

Employee Entry
objectClass inetOrgPerson

givenName John
surname Smith
mail john@inflix.com
jsmith@inflix.com
mobile +1 801 100 1000

Note Attribute names, by default, are case-insensitive. However, it is recommended to use camel case
format in LDAP operations.

You will notice that the mail attribute has two values. Attributes that are allowed to hold multiple values are
called multivalued attributes. Single-valued attributes, on the other hand, can only hold a single value. The
LDAP specification does not guarantee the order of the values in a multivalued attribute.
Each attribute type is associated with a syntax that dictates the format of the data stored as an attribute
value. For example, the mobile attribute type has a telephoneNumber syntax. This forces the attribute to
hold a string value with a length between 1 and 32.
Additionally, the syntax also defines the attribute value behavior during search operations. For example,
the givenName attribute has the syntax DirectoryString. This syntax enforces that only alphanumeric
characters are allowed as values. Table 1-2 lists some common attributes and their associated syntax
description.
Table 1-2 Common Entry Attributes

Attribute Type Syntax Description

commonName DirectoryString Stores the common name of a person.
company DirectoryString Stores the company’s name.
employeeNumber DirectoryString Stores the employee’s identification number in the organization.
givenName DirectoryString Stores the user’s first name.
jpegPhoto Binary Stores one or more images of the person.
mail IA5 String Stores a person’s SMTP mail address.
mobile TelephoneNumber Stores a person’s mobile number.
postalAddress Postal Address Stores the user’s ZIP or postal code.
postalCode DirectoryString Stores the user’s ZIP or postal code.
st DirectoryString Stores the state or province name.
street DirectoryString Stores the street address.
surname DirectoryString Stores the last name of the person.
telephoneNumber TelephoneNumber Stores the person’s primary telephone number.

uid DirectoryString Stores the user id.

title DirectoryString Stores the name of the position or the company’s function.
wwwhomepage DirectoryString Stores the official web page of the company.
The attributes in Table 1-2 are the most used for the developers and tools. Still, there is a big list of other
attributes depending on whether your vendor or the tool supports it or not; for example, on the official web
page10 of Microsoft, all the attributes are supported for the Active Directory.

Object Classes
In object-oriented languages, such as Java, we create a class and use it as a blueprint for creating objects. The
class defines the attributes/data (and behavior/methods) that these instances can have. Similarly, object
classes in LDAP determine the attributes an LDAP entry can have. These object classes also define which
attributes are mandatory and which are optional. Every LDAP entry has a special attribute aptly named
objectClass that holds the object class it belongs to. Looking at the objectClass value in the employee
entry in Table 1-1, we can conclude that the entry belongs to the inetOrgPerson class. Table 1-3 shows
the required and optional attributes in a standard LDAP person object class. The cn attribute holds the
person’s common name, whereas the sn attribute holds the person’s family name or surname.

Table 1-3 Person Object Class

Required Attributes Optional Attributes

sn description

telephoneNumber

cn userPassword
objectClass seeAlso

As in Java, an object class can extend other object classes. This inheritance will allow the child object
class to inherit parent class attributes. For example, the person object class defines attributes such as
common name and surname. The object class inetOrgPerson extends the person class and thus inherits
all the person’s attributes.
Additionally, inetOrgPerson defines attributes required for a person working in an organization, such
as departmentNumber and employeeNumber. One special object class, namely, top, does not have any
parents. All other object classes are decedents of top and inherit all the attributes declared in it. The top
object class includes the mandatory objectClass attribute. Figure 1-2 shows the object inheritance.
Figure 1-2 LDAP object inheritance
Most LDAP implementations come with standard object classes that can be used out of the box. Table 1-4
lists some of these LDAP object classes and their commonly used attributes.
Table 1-4 Common LDAP Object Classes

Object Class Attributes Description

top objectClass Defines the root object class. All other object classes must
extend this class.
organization o Represents a company or an organization.
The o attribute typically holds the name of the organization.
organizationalUnit ou Represents a department or similar entity inside an
organization.
person sn Represents a person in the directory and requires the sn
cn (surname) and cn (common name) attributes.
telephoneNumber
userPassword

organizationalPerson registeredAddress Subclasses that represent a person in an organization.

postalAddress postalCode
inetOrgPerson uid departmentNumber It provides additional attributes and can be used to represent a
employeeNumber givenName person working in today’s Internet- and intranet-based
manager organization. The uid attribute holds the person’s username or
user id.

On Oracle’s official website,11 you can find the list of LDAP object classes with information about the
Request for Comments (RFC), which added each object class.

Note In this book, you will see many references to RFCs. Request for Comments (RFC) is a series of
technical documents produced by the Internet Engineering Task Force (IETF)12 that specify certain
standards.
Each RFC has a number as part of the name and a series of sections with the specification. An RFC
could become obsolete to many other RFCs because a new specification about certain technology
appears, for example, a new version of LDAP.
On the RFC Editor web page,13 you can find information about RFCs and the publication process of the
new one.

Directory Schema
The LDAP directory schema is a set of rules determining the type of information stored in a directory.
Schemas can be considered packaging units and contain attribute type definitions and object class
definitions. The schema rules are verified before an entry can be stored in LDAP. This schema checking
ensures that the entry has all the required attributes and contains no attributes not part of the schema.
Figure 1-3 represents a generic LDAP schema.
Figure 1-3 LDAP generic schema
Like databases, directory schemas must be well designed to address issues like data redundancy. Before
implementing your schema, it is worth looking at publicly available standard schemas. These standard
schemas often contain all definitions to store the required data and, more importantly, ensure
interoperability across other directories.

Naming Model
The LDAP Naming model defines how entries are organized in a directory. It also determines how a
particular entry can be uniquely identified. The Naming model recommends that entries be stored logically
in a hierarchical fashion. This entry tree is often called a directory information tree (DIT). Figure 1-4
provides an example of a generic directory tree.

Figure 1-4 Generic DIT

The tree’s root is usually referred to as the base or suffix of the directory. This entry represents the
organization that owns the directory. The format of suffixes can vary from implementation to
implementation, but generally, there are three recommended approaches, as listed in Figure 1-5.

Figure 1-5 Directory suffix naming conventions

Note DC stands for domain component.

The first recommended technique is to use the organization’s domain name as the suffix. For example, if the
organization’s domain name is example.com, the directory suffix will be o=example.com. The second
technique also uses the domain name, but each name component is prepended with “dc=” and joined by
commas. So the domain name example.com would result in a suffix dc=example, dc=com. This technique
is proposed in RFC 224714 and is popular with Microsoft Active Directory. The third technique uses the
X.500 model and creates a suffix in the format o=organization name, c=country code. In the United States,
the suffix for the organization example would be o=example, c=us.
The naming model also defines naming and uniquely identifying entries in a directory. Entries with a
common immediate parent are uniquely identified via their relative distinguished name (RDN), also called
distinguished name (DN). The RDN is computed using one or more attribute/value pairs of the entry. In its
simplest case, RDN is usually of the form attribute-name = attribute value. Figure 1-6 provides a simplified
representation of an organization directory. Each person entry under ou=employees has a unique uid. So the
RDN for the first person entry would be uid=emp1, where emp1 is the employee’s user id.

Figure 1-6 Example of an organization directory

Note The distinguished name is not an actual attribute in the entry. It is a logical name associated with
the entry.

It is important to remember that RDN cannot be used to uniquely identify the entry in the entire tree.
However, this can be easily done by combining the RDNs of all the entries in the path from the top of the tree
to the entry. The result of this combination is referred to as distinguished name (DN). In Figure 1-6, the DN
for person 1 would be uid=emp1, ou=employees, dc=example, dc=com. Since the DN is made by combining
RDNs, if an entry’s RDN changes, the DNs of that entry and all its child entries also change.
There can be situations where a set of entries does not have a unique attribute. In those scenarios, one
option is to combine multiple attributes to create uniqueness. For example, we can use the consumer’s
common name and email address in the previous directory as an RDN. Multivalued RDNs are represented by
separating each attribute pair with a +, like so:

cn = Balaji Varanasi + mail=balaji@inflinx.com

Some special characters on the RDN must be escaped to prevent different problems. The special
characters are + (plus), = (equals), < (less than), > (greater than), ; (semicolon), , (comma), \ (backslash), #
(number sign), and ”.
There are different approaches to escape the characters, like adding the backslash (“\” ASCII 92) before
the special character; this approach is the most commonly used. The other replaces the special characters
with a backslash and hexadecimal digit, and the last one surrounds the attribute’s value with quotation
marks (“”).

Note Multivalued RDNs are usually discouraged. Creating a unique sequence attribute is recommended
in those scenarios to ensure uniqueness.

Functional Model
The LDAP Functional model describes the access and modification operations that can be performed on the
directory using the LDAP protocol. These operations fall into three categories: query, update, and
authentication.
The query operations are used to search and retrieve information from a directory. So whenever some
information needs to be read, a search query must be constructed and executed against LDAP. The search
operation takes a starting point within DIT, the search depth, and the attributes an entry must have for a
match. In Chapter 6, you’ll delve deep into searching and look at all the available options.
The update operations add, modify, delete, and rename directory entries. As the name suggests, the add
operation adds a new entry to the directory. This operation requires the DN of the entry to be created and a
set of attributes that constitute the entry. The delete operation takes a fully qualified DN of the entry and
deletes it from the directory. The LDAP protocol allows only the leaf entries to be deleted. The modified
operation updates an existing entry. This operation takes the entry’s DN and a set of modifications, such as
adding a new attribute, updating a new one, or removing an existing one. The rename operation can rename
or move entries in a directory.
The authentication operations are used for connecting and ending sessions between the client and the
LDAP server. A bind operation initiates an LDAP session between the client and server. Typically, this would
result in an anonymous session. The client can provide a DN and credentials to authenticate and create an
authenticated session. On the other hand, the unbind operation can be used to terminate an existing session
and disconnect from the server.
LDAP V3 introduced a framework for extending existing operations and adding new ones without
changing the protocol. You will take a look at these operations in Chapter 7.

Security Model
The LDAP Security model protects LDAP directory information from unauthorized access. The model
specifies which clients can access which parts of the directory and what kinds of operations (search vs.
update) are allowed.
The LDAP Security model is based on the client authenticating to the server. As discussed earlier, this
authentication process or bind operation involves the client supplying a DN identifying itself and a
password. An anonymous session is established if the client does not provide a DN and password. RFC
282915 defines a set of authentication methods that LDAP V3 servers must support. After successful
authentication, the access control models are consulted to determine whether the client has sufficient
privileges to do what is requested. Unfortunately, no standards exist for access control models, and each
vendor provides their implementations.

LDIF Format
The LDAP Data Interchange Format (LDIF) is a standard text-based format for representing directory
content and update requests. The LDIF format is defined in RFC 2849.16 LDIF files are typically used to
export data from one directory server and import it into another. It is also popular for archiving directory
data and applying bulk updates to a directory. You will use LDIF files to store your test data and refresh the
directory server between unit tests.
The basic format of an entry represented in LDIF is as follows:

#comment
dn: <distinguished name>
objectClass: <object class>
objectClass: <object class>
...
...
<attribute type>: <attribute value>
<attribute type>: <attribute value>
...

Lines in the LDIF file starting with a # character are considered comments. The dn and at least one
objectClass entry definition are considered required. Attributes are represented as name/value pairs
separated by a colon. Multiple attribute values are specified in separate lines and will have the same
attribute type. Since LDIF files are purely text based, binary data needs to be Base64 encoded before it is
stored as part of the LDIF file.
Blank lines separate multiple entries in the same LDIF file. Listing 1-1 shows an LDIF file with three
employee entries. Notice that the cn attribute is multivalued and is represented twice for each employee.

# Barbara’s Entry
dn: cn=Barbara J Jensen, dc=example, dc=com
# multi valued attribute
cn: Barbara J Jensen
cn: Babs Jensen
objectClass: personsn: Jensen
# Bjorn’s Entry
dn: cn=Bjorn J Jensen, dc=example, dc=com
cn: Bjorn J Jensen
cn: Bjorn Jensen
objectClass: person
sn: Jensen
# Base64 encoded JPEG photo
jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
# Jennifer’s Entry
dn: cn=Jennifer J Jensen, dc=example, dc=com
cn: Jennifer J Jensen
cn: Jennifer Jensen
objectClass: person
sn: Jensen
Listing 1-1 LDIF file with three employee entries

LDAP History
LDAP was developed by Tim Howes, Steve Kille, and Wengyik Yeong to create a network protocol to get data
out. In 1993 appeared the first draft of the RFC 1487,17 which contained the specification of LDAP based on
the access of X.500.
The first version acts as a proxy or gateway to X.500 directories, a comprehensive directory service
developed in the 1980s.
Tim Howes, with his colleagues, created the Open Source University of Michigan LDAP Implementation,
which became the reference for all the LDAP servers. The project’s website is active18 and accessible only for
historical reference.
The second version, the first to be operative (LDAPv2), was released in 1993 as an Internet Engineering
Task Force (IETF) Proposed Standard with basic operations like searching and modifying information. This
version offers limited functionality and has some problems related to the security mechanisms.
The third version, the latest available, was released in 1997, including many improvements related to
security, like Transport Layer Security (TLS) and the possibility of supporting referrals. It was based on RFCs
like RFC 225119 and RFC 4519,20 which explain the protocol and the supported data models. This version
became the de facto standard for directory services, and many applications have support to integrate and
use LDAP to obtain certain information.

LDAP Vendors
LDAP gained wide support from various vendors. There has also been a strong open source movement to
produce LDAP servers. Table 1-5 outlines some of the popular directory servers and include the information
about which is the docker image to run each of them with a small configuration.
Table 1-5 LDAP Vendors
Directory Vendor Open URL
Name Source?
Apache DS Apache Yes https://directory.apache.org/apacheds/ https://hub.docke
OpenLDAP OpenLDAP Yes https://www.openldap.org/ https://hub.d

Tivoli IBM No https://www.ibm.com/docs/en/i/7.5?topic=services-tivoli- No existing official i

Directory directory-server-i-ldap
Server
Active Microsoft No https://learn.microsoft.com/en-us/windows/win32/adsi/so- No existing official i
Directory what-is-active-directory?redirectedfrom=MSDN
eDirectory Novell No https://www.microfocus.com/en-us/cyberres/identity- No existing official
access-management/edirectory

Oracle Oracle No https://www.oracle.com/security/identity- No existing official i

Directory (formerly management/technologies/directory-server-enterprise-
Server Sun) edition
Enterprise
Edition
(ODSEE)
Oracle No https://www.oracle.com/middleware/technologies/internet- No existing official i
Internet directory.html
Directory
(OID)
OpenDJ ForgeRock Yes https://github.com/OpenIdentityPlatform/OpenDJ https://hub.docker
ApacheDS and OpenDJ are pure Java implementations of LDAP directories. You will be using these two
servers for unit and integration testing of the code throughout this book.

Sample Application
Throughout this book, you will be working with a directory for a hypothetical book library. I have chosen the
library because the concept is universal and easy to grasp. A library usually stores books and other
multimedia that patrons can borrow. Libraries also employ people to take care of daily library operations. To
keep things manageable, the directory will not store book information. A relational database is suitable for
recording book information. Figure 1-7 shows the LDAP directory tree for our library application.

Figure 1-7 Library DIT

I have used the RFC 224714 convention in this directory tree to name the base entry. The base entry has
two organizational unit entries that hold the employees’ and patrons’ information. The ou=employees part
of the tree will hold all the library employee entries. The ou=patrons part of the tree will hold the library
patron entries. Both library employee and patron entries are of the type inetOrgPerson objectClass.
Both employees and patrons access library applications using their unique login id. Thus, the uid attribute
will be used as the RDN for entries.
Summary
LDAP and applications that interact with LDAP have become a key part of every enterprise today. This
chapter covered the basics of the LDAP directory. You learned that LDAP stores information as entries. Each
entry is made up of attributes that are simply key-value pairs. These entries can be accessed via their
distinguished names. You also saw that LDAP directories have schemas that determine the type of
information that can be stored.
The next chapter will look at communicating with an LDAP directory using Java Naming and Directory
Interface (JNDI). In the chapters following Chapter 2, you will focus on using Spring LDAP for developing
LDAP applications.

Footnotes
1 https://docs.oracle.com/javase/jndi/tutorial/ldap/models/x500.html

2 https://en.wikipedia.org/wiki/Write_Once_Read_Many

3 https://www.techtarget.com/searchstorage/definition/WORM-write-once-read-many

4 https://www.oracle.com/in/database/what-is-a-relational-database/

5 https://www.ibm.com/products/db2

6 https://www.mysql.com/

7 https://www.postgresql.org/

8 https://cassandra.apache.org/_/index.html

9 https://www.mongodb.com/

10 https://learn.microsoft.com/en-us/windows/win32/adschema/attributes-all

11 https://docs.oracle.com/cd/E24001_01/oid.1111/e10035/schema_objclass.htm

12 https://www.ietf.org/

13 https://www.rfc-editor.org/

14 https://www.ietf.org/rfc/rfc2247.txt

15 https://www.ietf.org/rfc/rfc2829.txt
16 https://www.ietf.org/rfc/rfc2849.txt

17 https://datatracker.ietf.org/doc/html/rfc1487

18 www.umich.edu/~dirsvcs/ldap/ldap.html

19 https://datatracker.ietf.org/doc/html/rfc2251

20 https://datatracker.ietf.org/doc/html/rfc4519
© The Author(s), under exclusive license to APress Media, LLC, part of Springer Nature 2023
B. Varanasi, A. Sacco, Practical Spring LDAP
https://doi.org/10.1007/979-8-8688-0002-3_2

2. Java Support for LDAP

Balaji Varanasi1 and Andres Sacco2
(1) Salt Lake City, UT, USA
(2) Buenos Aires, Buenos Aires, Argentina

As the name suggests, the Java Naming and Directory Interface (JNDI) provides a standardized
programming interface for accessing naming and directory services. It is a generic Application
Programming Interface (API) that can access various systems, including file systems, Enterprise Java Beans
(EJB),1 Common Object Request Broker Architecture (CORBA),2 and directory services such as the Network
Information Service and LDAP. JNDI’s abstractions to directory services can be viewed as similar to Java
Database Connectivity (JDBC)’s abstractions to relational databases.
The JNDI architecture consists of an Application Programming Interface or API and a Service Provider
Interface or SPI. Developers program their Java applications using the JNDI API to access directory/naming
services. Vendors implement the SPI with details that deal with actual communication to their particular
service/product. Such implementations are referred to as service providers. Figure 2-1 shows the JNDI
architecture and a few naming and directory service providers. This pluggable architecture provides a
consistent programming model and prevents the need to learn a separate API for each product.

Figure 2-1 JNDI architecture

The JNDI has been part of the standard JDK distribution since Java version 1.3 and has not moved to
Jakarta like other packages. The API itself is spread across five packages:
The javax.naming3 package contains classes and interfaces for looking up and accessing objects in a
naming service.
The javax.naming.directory4 package contains classes and interfaces that extend the core javax.naming
package. These classes can access directory services and perform advanced operations such as filtered
searching.
The javax.naming.event5 package has functionality for event notification when accessing naming and
directory services.
The javax.naming.ldap6 package contains classes and interfaces that support the LDAP Version 3
controls and operations. Later chapters will examine controls and operations.
The javax.naming.ldap.spi7 package contains classes to support defining custom DNS for LDAP. The
support of this feature has appeared since Java 12.
The javax.naming.spi8 package contains the SPI interfaces and classes. As mentioned earlier, service
providers implement SPI, and we will not cover these classes in this book.
LDAP Using JNDI
While JNDI allows access to a directory service, it is essential to remember that JNDI is not a directory or a
naming service. Thus, we need a running LDAP directory server to access LDAP using JNDI.
Accessing LDAP using JNDI usually involves three steps:
Connect to LDAP
Perform LDAP operations
Close the resources

Note Check if you have installed the correct version of Java on your machine. To do this, look at
Appendix A, which explains how to do it.
If you don’t have a test LDAP server available, please refer to the steps in Appendix B for installing a
local LDAP server or running it using Docker. The explanation about how to install Docker and check if
everything is okay appears in Appendix A.
This chapter aims to show how you can do different operations on LDAP using Java without any
framework. With this approach, you will see the complexity of doing certain operations and writing
many lines of code to do something simple with the assistance of some framework like Spring LDAP.

Connect to LDAP
All the naming and directory operations using JNDI are performed relative to a context. So the first step in
using JNDI is to create a context that acts as a starting point on the LDAP server. Such a context is referred to
as an initial context. Once an initial context is established, it can look up other contexts or add new objects.
The Context interface and InitialContext class in the javax.naming package can be used for creating an
initial naming context. Since we are dealing with a directory here, we will use a more specific DirContext
interface and its implementation InitialDirContext. Both DirContext and InitialDirContext are available
inside the javax.naming.directory package. The directory context instances can be configured with
properties that provide information about the LDAP server. The code in Listing 2-1 creates a context for an
LDAP server running locally on port 1389.

Properties environment = new Properties();

environment.setProperty(DirContext.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
environment.setProperty(DirContext.PROVIDER_URL, "ldap://localhost:11389");
DirContext context = new InitialDirContext(environment);
Listing 2-1 How to create a basic connection with LDAP

Note In the following parts of the chapter, I will explain in detail the most relevant parts to connect
and execute some operations to LDAP.
By the end of this chapter, you will see the different outputs of the execution of the different methods.

In Listing 2-1, we have used the INITIAL_CONTEXT_FACTORY constant to specify the service provider class
that needs to be used. Here, we use the sun provider com.sun.jndi.ldap.LdapCtxFactory, which is part of
the standard JDK distribution. The PROVIDER_URL is used to specify the fully qualified URL of the LDAP
server. The URL includes the protocol (LDAP for nonsecure or LDAPs for secure connections), the server
hostname, and the port.

Note The declaration of the type on a variable has been optional since Java 14, so you don’t need to
declare that the variable environment has the type Properties; you can replace the keyword var, and the
compiler will infer the correct type.
This change does not add any feature related to the performance, so I decided to keep the code
simple.
Once a connection to the LDAP server is established, the application can identify itself by providing
authentication information. Contexts like the one created in Listing 2-1, where authentication information
is not provided, are called anonymous contexts. LDAP servers usually have ACLs (access list controls) that
restrict operations and information to certain accounts. So it is very common in enterprise applications to
create and use authenticated contexts. Listing 2-2 provides an example of creating an authenticated context.
Notice that we have used three additional properties to provide the binding credentials. The
SECURITY_AUTHENTICATION property is set to simple, indicating that we will use a plain text username
and password for authentication.

Properties environment = new Properties();

environment.setProperty(DirContext.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
environment.setProperty(DirContext.PROVIDER_URL, "ldap://localhost:11389");
environment.setProperty(DirContext.SECURITY_AUTHENTICATION, "simple");
environment.setProperty(DirContext.SECURITY_PRINCIPAL, "Directory Manager");
environment.setProperty(DirContext.SECURITY_CREDENTIALS, "secret");
DirContext context = new InitialDirContext(environment);
Listing 2-2 How to connect on LDAP using the credentials

Note On the declaration of the different properties, you can see the class DirContext appear many
times, which is not the best approach, so if you want to reduce the duplicates, you can simplify using
static imports. For example, you can declare the static import like this: import static
javax.naming.directory.DirContext.INITIAL_CONTEXT_FACTORY, and on the declaration of the variable,
just use PROVIDER_URL.

Any problems occurring during the context creation will be reported as instances of
javax.naming.NamingException. NamingException is the superclass of all the exceptions thrown by the
JNDI API. This is a checked exception and must be handled properly for the code to compile. Table 2-1 lists
common exceptions we will likely encounter during JNDI development.
Table 2-1 Common LDAP Exceptions

Exception Description
AttributeInUseException Thrown when an operation tries to add an existing attribute.
AttributeModificationException Thrown when an operation tries to add/remove/update an attribute and violates the
attribute’s schema or state. For example, adding two values to a single-valued attribute
would result in this exception.
CommunicationException Thrown when an application fails to communicate (network problems) with the LDAP
server.
InvalidAttributesException Thrown when an operation tries to add or modify an attribute set that has been specified
incompletely or incorrectly. For example, adding a new entry without specifying all the
required attributes would result in this exception.
InvalidAttributeValueException Thrown when an operation tries to add or modify a value of an attribute that enters a
conflict with the schema definition.
InvalidSearchFilterException Thrown when a search operation is given a malformed search filter.
LimitExceededException Thrown when a search operation abruptly terminates as a user- or system-specified result
limit is reached.
NameAlreadyBoundException Thrown to indicate that an entry cannot be added as the associated name is already bound
to a different object.
NotContextException Thrown when an operation process until the context is required to continue.
OperationNotSupportedException Thrown when a context implementation does not support a specific operation when
invoked.
PartialResultException Thrown to indicate that only a portion of the expected results is returned and the
Exception Description
operation cannot be completed.
SizeLimitExceededException Thrown when a method produces a result that exceeds a size-related limit.
TimeLimitExceededException Thrown when a method produces a result that exceeds a time-related limit.

LDAP Operations
Once we obtain an initial context, we can perform various operations on LDAP using the context. These
operations can involve looking up another context, creating a new one, and updating or removing an
existing one. Here is an example of looking up another context with DN
uid=emp1,ou=employees,dc=inflinx,dc=com:

DirContext
anotherContext = context.lookup("uid=emp1,ou=employees,dc=inflinx,dc=com");

We will closely examine each of these operations in the coming section.

Closing Resources
After completing all desired LDAP operations, it is important to close the context and any other associated
resources properly. Closing a JNDI resource simply involves calling the close method on it. Listing 2-3 shows
the code associated with closing a DirContext. The code shows that the close method also throws a
NamingException that needs to be properly handled.

try {
context.close();
} catch (NamingException e) {
//Do something with the exception, like log the error.
}
Listing 2-3 How to close the connection with LDAP

Note The previous block does not use “try-with-resources” because DirContext does not implement
the auto closeable.

Creating a New Entry

Consider the case where a new employee starts with our hypothetical library, and we are asked to add their
information to LDAP. As we have seen earlier, before an entry can be added to LDAP, it is necessary to obtain
an InitialDirContext. Listing 2-4 defines a reusable method for doing this.

private DirContext getContext() throws NamingException{

Properties environment = new Properties();
environment.setProperty(DirContext.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
environment.setProperty(DirContext.PROVIDER_URL,
"ldap://localhost:1389");
environment.setProperty(DirContext.SECURITY_PRINCIPAL, "cn=Directory
Manager");
environment.setProperty(DirContext.SECURITY_CREDENTIALS, "secret");
return new InitialDirContext(environment);
}
Listing 2-4 Create a method to connect with LDAP
 Once we have the initial context, adding the new employee information is straightforward, as shown in
Listing 2-5.

public void addEmployee(Employee employee) {

DirContext context = null;
try {
context = getContext();
// Populate the attributes
Attributes attributes = new BasicAttributes();
attributes.put(new BasicAttribute("objectClass", "inetOrgPerson"));
attributes.put(new BasicAttribute("uid", employee.getUid()));
attributes.put(new BasicAttribute("givenName",
employee.getFirstName()));
attributes.put(new BasicAttribute("surname", employee.getLastName()));
attributes.put(new BasicAttribute("commonName",
employee.getCommonName()));
attributes.put(new BasicAttribute("departmentNumber",
employee.getDepartmentNumber()));
attributes.put(new BasicAttribute("mail", employee.getEmail()));
attributes.put(new BasicAttribute("employeeNumber",
employee.getEmployeeNumber()));
Attribute phoneAttribute =
new BasicAttribute("telephoneNumber");
for(String phone : employee.getPhone()) {
phoneAttribute.add(phone);
}
attributes.put(phoneAttribute);
// Get the fully qualified DN
String dn = "uid="+employee.getUid() + "," + BASE_PATH;
// Add the entry
context.createSubcontext("dn", attributes);
} catch(NamingException e) {
// Handle the exception and show the description of the problem
} finally {
closeContext(context);
}
}
Listing 2-5 Add a new entry on LDAP

As you can see, the first step in the process is to create a set of attributes that needs to be added to the
entry. JNDI provides the javax.naming.directory.Attributes interface and its implementation
javax.naming.directory.BasicAttributes to abstract an attribute collection. We then add the employee’s
attributes one at a time to the collection using JNDI’s javax.naming.directory.BasicAttribute class. Notice
that we have taken two approaches in creating the BasicAttribute class. In the first approach, we added the
single-valued attributes by passing the attribute name and value to BasicAttribute’s constructor. To handle
the multivalued attribute telephone, we first created the BasicAttribute instance by just passing in the
name. Then, we individually added the telephone values to the attribute. Once all the attributes are added,
we invoked the createSubcontext method on the initial context to add the entry. The createSubcontext
method requires the fully qualified DN of the entry to be added.
Notice that we have delegated the closing of the context to a separate method closeContext. Listing 2-6
shows its implementation.

private void closeContext(DirContext context) {

try {
if (null != context) {
context.close();
 }
} catch (NamingException e) {
// Handle the exception and show the description of the problem
}
}
Listing 2-6 How to close the connection with LDAP

Updating an Entry
Modifying an existing LDAP entry can involve any of the following operations:
Add a new attribute and value(s) or add a new value to an existing multivalued attribute.
Replace an existing attribute value(s).
Remove an attribute and its value(s).
To allow modification of the entries, JNDI provides an aptly named
javax.naming.directory.ModificationItem class.
A ModificationItem consists of the type of modification to be made and the attribute under modification.
The following code creates a modification item for adding a new telephone number:

Attribute telephoneAttribute = new BasicAttribute("telephone",

"80181001000");
ModificationItem modificationItem = new ModificationItem(DirContext.
ADD_ATTRIBUTE, telephoneAttribute);

Notice that in the preceding code, we have used the constant ADD_ATTRIBUTE to indicate that we want
an add operation. Table 2-2 provides the supported modification types along with their descriptions.

Table 2-2 LDAP Modification Types

Modification Type Description

ADD_ATTRIBUTE Adds the attribute with the supplied value or values to the entry. If the attribute does not exist, then it
will be created. If the attribute is multivalued, this operation adds the specified value(s) to the
existing list. However, this operation on an existing single-valued attribute will result in the
AttributeInUseException.
REPLACE_ATTRIBUTE Replaces existing attribute values of an entry with the supplied values. If the attribute does not exist,
then it will be created. If the attribute already exists, all its values will be replaced.
REMOVE_ATTRIBUTE Removes the specified value from the existing attribute. If no value is specified, the entire attribute
will be removed. If the specified value does not exist in the attribute, the operation will throw a
NamingException. If the value to be removed is the only value of the attribute, then the attribute is
also removed.

The code for updating an entry is provided in Listing 2-7. The modifyAttributes method takes the entry’s
fully qualified DN and an array of modification items.

public void update(String dn, ModificationItem[] items) {

DirContext context = null;
try {
context = getContext();
context.modifyAttributes(dn, items);
} catch (NamingException e) {
// Handle the exception and show the description of the problem
} finally {
closeContext(context);
}
}
Listing 2-7 How to update an entry
Removing an Entry
Removing an entry using JNDI is a straightforward process shown in Listing 2-8. The destroySubcontext
method takes the fully qualified DN of the entry that needs to be deleted.

public void remove(String dn) {

DirContext context = null;
try {
context = getContext();
context.destroySubcontext(dn);
} catch (NamingException e) {
// Handle the exception and show the description of the problem
} finally {
closeContext(context);
}
}
Listing 2-8 How to remove an entry

Many LDAP servers don’t allow an entry to be deleted if it has child entries. In those servers, deleting a
non-leaf entry would require traversing the subtree and deleting all the child entries. Then the non-leaf
entry can be deleted. Listing 2-9 shows the code involved in deleting a subtree.

public void removeSubtree(DirContext ctx, String root) throws

NamingException {
NamingEnumeration enumeration = null;
try {
enumeration = ctx.listBindings(root);
while (enumeration.hasMore()) {
Binding childEntry = (Binding) enumeration.next();
LdapName childName = new LdapName(root);
childName.add(childEntry.getName());

try {
ctx.destroySubcontext(childName);
} catch (ContextNotEmptyException e) {
removeSubtree(ctx, childName.toString());
ctx.destroySubcontext(childName);
}
}
} catch (NamingException e) {
// Handle the exception and show the description of the problem
} finally {
try {
enumeration.close();
} catch (Exception e) {
// Handle the exception and show the description of the problem
}
}
}
Listing 2-9 How to remove a subtree of elements

Note The OpenDJ LDAP server supports a special subtree delete control that can cause the server to
delete the non-leaf entry and all its child entries when attached to a delete request. We will look at using
LDAP controls in Chapter 7.
Searching Entries
Searching for information is usually the most common operation against an LDAP server. To perform a
search, we need to provide information such as the scope of the search, what we are looking for, and what
attributes need to be returned. In JNDI, this search metadata is provided using the SearchControls class.
Listing 2-10 provides an example of a search control with subtree scope and returns the givenName and
telephoneNumber attributes. The subtree scope indicates that the search should start from the given base
entry and should search all its subtree entries. We will look at the different scopes available in detail in
Chapter 6.

SearchControls searchControls = new SearchControls();

searchControls.setSearchScope(SearchControls.SUBTREE_SCOPE);
searchControls.setReturningAttributes(new String[]{"givenName",
"telephoneNumber"});
Listing 2-10 The attributes to return for each entry

Once the search controls are defined, the next step is invoking one of the many search methods in the
DirContext instance. Listing 2-11 provides the code that searches all the employees and prints their first
name and telephone number.

public void search() {

DirContext context = null;
NamingEnumeration<SearchResult> searchResults = null;
try {
context = getContext();
// Setup Search meta data
SearchControls searchControls = new SearchControls();
searchControls.setSearchScope(SearchControls.SUBTREE_SCOPE);
searchControls.setReturningAttributes(new String[] { "givenName",
"telephoneNumber" });
searchResults = context.search("dc=inflinx,dc=com", "
(objectClass=inetOrgPerson)", searchControls);

while (searchResults.hasMore()) {
SearchResult result = searchResults.next();
Attributes attributes = result.getAttributes();
String firstName = (String) attributes.get("givenName").get();

// Read the multi-valued attribute

Attribute phoneAttribute = attributes.get("telephoneNumber");
String[] phone = new String[phoneAttribute.size()];
NamingEnumeration phoneValues = phoneAttribute.getAll();

for (int i = 0; phoneValues.hasMore(); i++) {

phone[i] = (String) phoneValues.next();
}
//You can use logback or system.out
logger.info(firstName + "> " + Arrays.toString(phone));
}
} catch (NamingException e) {
// Handle the exception and show the description of the problem
} finally {
try {
if (null != searchResults) {
searchResults.close();
}
 closeContext(context);
} catch (NamingException e) {
// Handle the exception and show the description of the problem
}
}
}
Listing 2-11 How to search elements
Here, we used the search method with three parameters: a base that determines the search’s starting
point, a filter that narrows down the results, and a search control. The search method returns an
enumeration of SearchResults. Each search result holds the LDAP entry’s attributes. Hence, we loop through
the search results and read the attribute values. Notice that we obtain another enumeration instance for
multivalued attributes and read its values one at a time. In the final part of the code, we close the result
enumeration and the context resources.

Check How the Operations Work

After that, reading all the source code of the different operations could be a good idea to check if everything
works fine or not. To do this, a possible approach is to create a class that invokes the different methods of
accessing LDAP using JNDI.
Listing 2-12 shows you a class App that creates an instance of a class JndiLdapDaoImpl, which contains
all the methods of the different operations you see from Listings 2-4 to 2-11. In the case of Listing 2-12, you
only will execute one operation because it’s more simple to analyze the logs.

public class App {

public static void main(String[] args) {
JndiLdapDaoImpl jli = new JndiLdapDaoImpl();
//Search
jli.search();
}
}
Listing 2-12 A class that invokes the method search

If you run the application with the previous block of code, you will see something like Listing 2-13.

12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -

Chie> [+1 622 858 9026]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chin> [+1 191 452 7983]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
ChinFui> [+1 439 500 8383]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Ching-Long> [+1 407 407 2419]
12:13:14.186 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chip> [+1 833 470 1660]
Listing 2-13 The result of obtaining all the employees from LDAP

The next step is to add an employee and obtain all the employees to check whether the operations were
okay. Let’s make some little modifications to the class App, like Listing 2-14.

public class App {

public static void main(String[] args) {
JndiLdapDaoImpl jli = new JndiLdapDaoImpl();

//Add and search

jli.addEmployee(getEmployee());
 jli.search();
}

private static Employee getEmployee() {

Employee employee = new Employee();
employee.setEmployeeNumber("50001");
employee.setFirstName("Andres");
employee.setLastName("Sacco");
employee.setEmail("sacco.andres@gmail.com");

employee.setUid("employee30");
employee.setPhone(new String[] { "+54 9 1161484" });
employee.setCommonName("Andres");
return employee;
}
}
Listing 2-14 A class that invokes the methods add and search
If you run the application with the previous block of code, you will see something like Listing 2-15.
Check that a new employee appears at the end of the logs with the name “Andres.”

12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -

Chie> [+1 622 858 9026]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chin> [+1 191 452 7983]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
ChinFui> [+1 439 500 8383]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Ching-Long> [+1 407 407 2419]
12:13:14.186 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chip> [+1 833 470 1660]
12:13:14.187 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Andres> [+54 9 1161484]
Listing 2-15 The result of adding an employee and obtaining all the employees from LDAP

After you add a new employee, the next operation to check is the deletion of an entry from LDAP. You
must send the dn like this: uid=employee29,ou=employees,dc=inflinx,dc=com to remove the
employee29. Let’s make some little modifications to the class App, like Listing 2-16.

public class App {

public static void main(String[] args) {
JndiLdapDaoImpl jli = new JndiLdapDaoImpl();

//Remove and search

jli.remove("uid=employee29,ou=employees,dc=inflinx,dc=com");
jli.search();
}
}
Listing 2-16 A class that invokes the methods remove and search

If you run the application with the previous block of code, you will see something like Listing 2-17. If
you compare the output of this execution with Listing 2-16, you will see that from the list of employees, the
previous one to “Andres,” which is employee number 29 with the name “Chip” was removed.

12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -

Chie> [+1 622 858 9026]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chin> [+1 191 452 7983]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
ChinFui> [+1 439 500 8383]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Ching-Long> [+1 407 407 2419]
12:13:14.187 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Andres> [+54 9 1161484]
Listing 2-17 The result of removing an employee and obtaining all the employees from LDAP
The last operation to check how it works is to update an existing entry on LDAP. To make this more
interesting, you will update the givenName of the employee you added to Listing 2-14. Let’s modify your
application’s main class to call the update method, as shown in Listing 2-18.

public class App {

public static void main(String[] args) {
JndiLdapDaoImpl jli = new JndiLdapDaoImpl();

//Update and search

BasicAttribute attribute = new BasicAttribute("givenName", "Andy");
ModificationItem[] items = {new
ModificationItem(DirContext.REPLACE_ATTRIBUTE, attribute)};
jli.update("uid=employee30,ou=employees,dc=inflinx,dc=com", items);
jli.search();
}
}
Listing 2-18 A class that invokes the methods update and search

If you run the application with the previous block of code, you will see something like Listing 2-19.
Check that the last entry changed the givenName attribute from “Andres” to “Andy.”

12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -

Chie> [+1 622 858 9026]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Chin> [+1 191 452 7983]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
ChinFui> [+1 439 500 8383]
12:23:40.978 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Ching-Long> [+1 407 407 2419]
12:13:14.187 [main] INFO com.apress.book.ldap.dao.impl.JndiLdapDaoImpl -
Andy> [+54 9 1161484]
Listing 2-19 The result of updating an attribute for an employee and obtaining all the employees from LDAP

As you can see from the different examples of the results of the operations, all of them work fine and
give the information you requested. Still, suppose something bad happens during the execution of the
operation. In that case, the NamingException will give you some information about the reason for the
exception, so try to use a mechanism to save the logs in a place accessible to anyone.

JNDI Drawbacks
Though JNDI provides a nice abstraction for accessing directory services, it suffers from several drawbacks:
Explicit Resource Management
The developer is responsible for closing all the resources. This is very error-prone and can result in
memory leaks.
Plumbing Code
 The preceding methods have much plumbing code that can be easily abstracted and reused. This
plumbing code makes testing harder, and the developer must learn the API’s nitty-gritty.
Checked Exceptions
The usage of checked exceptions, especially in irrecoverable situations, is questionable. Having to
explicitly handle NamingException in those scenarios usually results in empty try-catch blocks.

Summary
Java offers you a set of interfaces and classes to access and execute different operations on LDAP simply if
you do not need to do complex operations.
The next chapter will look at how to do some operations using Spring LDAP, as you’ve seen in this
chapter. The idea is to show you how Spring LDAP reduces the complexity of certain operations like Spring
Data does with the applications that need to access a database.

Footnotes
1 https://en.wikipedia.org/wiki/Jakarta_Enterprise_Beans

2 https://www.ibm.com/docs/en/sdk-java-technology/8?topic=orb-corba

3 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/package-
summary.html

4 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/directory/pack
age-summary.html

5 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/event/package-
summary.html

6 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/ldap/package-
summary.html

7 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/ldap/spi/packa
ge-summary.html

8 https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/spi/package-
summary.html
© The Author(s), under exclusive license to APress Media, LLC, part of Springer Nature 2023
B. Varanasi, A. Sacco, Practical Spring LDAP
https://doi.org/10.1007/979-8-8688-0002-3_3

3. Introducing Spring LDAP

Balaji Varanasi1 and Andres Sacco2
(1) Salt Lake City, UT, USA
(2) Buenos Aires, Buenos Aires, Argentina

Spring LDAP1 provides simple, clean, and comprehensive support for LDAP programming in Java. This
project started on SourceForge in 2006 under the name LdapTemplate to simplify access to LDAP using
JNDI. The project later became part of the Spring Framework portfolio and has come a long way. Figure 3-1
depicts the architecture of a Spring LDAP–based application.

Figure 3-1 Spring LDAP architecture directory

The application code uses the Spring LDAP API to perform LDAP server operations. The Spring LDAP
framework contains all of the LDAP-specific code and abstractions. Spring LDAP, however, will rely on the
Spring Framework for some of its infrastructural needs.
The Spring Framework has become today’s standard for developing Java-based enterprise applications.
Among many other things, it provides a dependency injection–based lightweight alternative to the JEE
programming model. The Spring Framework is the base for Spring LDAP and all other Spring portfolio
projects, such as Spring MVC and Spring Security.

Motivation
In the previous chapter, we discussed the shortcomings of the JNDI API. A notable drawback of JNDI is that it
is very lengthy; almost all of the code in Chapter 2 has to do with plumbing and very little with application
logic. Spring LDAP addresses this problem by providing template and utility classes that take care of the
plumbing code so the developer can focus on business logic.
Another notable issue with JNDI is that it requires the developer to explicitly manage resources such as
LDAP contexts. This can be very error-prone. Forgetting to close resources can result in leaks and can
quickly bring down an application under heavy load. Spring LDAP manages these resources on your behalf
and automatically closes them when you no longer need them. It also provides the ability to pool LDAP
contexts, which can improve performance.
Any problems that arise during the execution of JNDI operations will be reported as instances of
NamingException or its subclasses. NamingException is a checked exception, and thus the developer
is forced to handle it. Data access exceptions are usually not recoverable, and most often, only a little can be
done to catch these exceptions. To address this, Spring LDAP provides a consistent unchecked exception
hierarchy that mimics NamingException. This allows the application designer to choose when and where
to handle these exceptions.
 Finally, plain JNDI programming is hard and daunting for new developers. Spring LDAP, with its
abstractions, makes working with JNDI more enjoyable. Additionally, it provides various features such as
Object-Directory Mapping and transaction support, making it an important tool for any enterprise LDAP
developer.

Documentation and Source Code Spring LDAP

Spring Framework portfolio projects can be checked in the documentation from the official website.2 A
direct link is available on the Spring LDAP website,3 or you can check the source code at the GitHub
repository.4
Spring LDAP source code can provide valuable insights into the framework architecture. It also includes
a rich test suite that can serve as additional documentation and help you understand the framework. You
should download and look at the source code. The Git repository also holds a sandbox folder that contains
several experimental features that may or may not make it into the framework.

Spring LDAP Packaging

Now that you can access the Spring LDAP framework’s documentation and source code, let’s delve into the
different components. The LDAP framework is packaged into six components, and Table 3-1 briefly
describes each component.

Table 3-1 Spring LDAP Distribution Modules

Component Description
spring-ldap-core It contains all the classes necessary for using the LDAP framework. This jar is required in all
applications.
spring-ldap-core- It contains classes and extensions that are specific to Java 5 and higher. Applications running under Java
tiger 5 should not use this jar.
spring-ldap-test It contains classes and utilities that make testing easier. It also includes classes for starting and
stopping in-memory instances of the ApacheDS LDAP server.
spring-ldap-ldif- It contains classes for parsing ldif format files.
core

spring-ldap-ldif- It contains classes necessary to integrate ldif parser with Spring Batch Framework.
batch
spring-ldap-odm It contains classes for enabling and creating Object-Directory Mappings.

Along with Spring Framework, you need additional jar files for compiling and running applications using
Spring LDAP. Table 3-2 lists some of these dependent jar files and describes why they are used.

Table 3-2 Spring LDAP

Library Description

slf4j5 Logging is used internally by Spring LDAP and Spring Framework. This is a required jar to be included in
applications.
spring-core Spring library that contains core utilities used internally by Spring LDAP. This is a required library for using
Spring LDAP.
spring-beans Spring Framework library used for creating and managing Spring Beans. Spring LDAP requires another library.
spring- Spring library that is responsible for dependency injection. This is required when using Spring LDAP inside a
context Spring application.
spring-tx Spring Framework library that provides transaction abstractions. This is required when using Spring LDAP
transaction support.
spring-jdbc The library simplifies access to the database using JDBC under the covers. This is an optional library and
should be used for transaction support.
Other documents randomly have
different content
 neighboring squires with matter for talk over their October, and
the neighboring rectors with topics for sharp sermons against
Whiggery and Popery.

It is scarcely necessary to say that there were then no

provincial newspapers. Indeed except at the capital and at the
two Universities there was scarcely a printer in the kingdom.

This was the condition of the newspaper business at the end of

the reign of King Charles II.—a period distinguished by less interest
in literature and study than any period of England’s history after the
Elizabethan revival of learning. The reading of books and the search
for information had been abandoned in the quest for pleasure. The
people had joined in imitating the profligacy, the licentiousness and
the revels of Charles’s court. They who champion the newspaper as
a great uplifting influence in community might instance these
profligate days in which there were no newspapers and compare
them with later years.

But the opening of the eighteenth century brought fresh impetus

to study and a new interest in literature. Several weekly newspapers
had been set going. The first daily newspaper was started in London
in 1702. It was called the Courant. It was a small single-sheet
publication printed on one side only, and it gave but a meager
assortment of news items. It refrained from expressing opinions, the
editor saying that “he would give no comments of his own as he
assumed that people had sense enough to make reflections for
themselves.” Scores of editors even to the present day have
launched initial numbers of their editions with this same resolution,
expressed in the same way, but somehow it does not last long.

Then came the Review founded by Defoe, and Richard Steele’s

Tatler and the Spectator by Steele and Joseph Addison, which
publications mark the real beginnings of journalism. By this time
Pope and Swift, William Walsh, whom Dryden praised as a great
critic, and Arthur Maynwaring and others of the famous Kit Cat Club
were writing for the periodicals.

Editorial comment, or the expression of editorial opinion seems to

have had no place in newspapers until toward the close of the reign
of King Charles II. Then, while the London Gazette, appearing under
government direction, was printing news only, Sir Roger Lestrange
was permitted to print a journal of comment without news, called
the Observator. Lestrange had been a Tory pamphleteer, and for a
short time had edited small news-sheets and under the government.
He had been Surveyor of Printing Offices and Licensor of the Press.
The Observator was ferociously against the Whigs and the
Protestants. Because editorial comment was new, it focused much
attention. Here was the first editor to write violent political editorial
articles. He confined his subjects to politics and to religion which was
then a part of the politics of the day. He inspired a host of imitators
and the leading article, of which he was the parent, has been the
leading feature of all journalism ever since. Great in its political use,
immediately after him, were Dean Swift in his Examiner, and Daniel
Defoe in the Review which he started in 1704 while in jail for
political offense.

It was just at the beginning of the eighteenth century that Steele

and Addison began their Tatler and Spectator. Their first impulse
was to write of politics, for Steele was alive with political zeal and
Addison was interested; but presently they seemingly sensed the
opportunity for success in the new direction of a publication given to
the elucidation and the discussion of general topics, of subjects on
which politics was unlikely to produce diversion of opinion—social
life, play-house criticism, literature, morals, ethics and personal
conduct. The Spectator was printed daily. To the policy of minimizing
politics and exalting general topics of interest it adhered.

Newspapers and periodicals increased rapidly after this time.

Henry Fielding, the novelist, was editor of the True Patriot in 1745
and the Jacobite Journal in 1747. Dr. Samuel Johnson started the
Rambler in 1750 and the Idler in 1758. In 1714, eleven papers were
appearing in London. In 1733, the number had increased to
eighteen and in 1776, to fifty-three.

John Wilkes in his newspaper the North Briton accused the king of
lying in his address at the opening of Parliament in 1762, for which
Wilkes was committed to the tower and expelled from the house, of
which he had been a member.

Oliver Goldsmith wrote his delightful letters from “A Citizen of the

World” for the Public Ledger. Samuel Taylor Coleridge, Hazlitt and
John Campbell were writers for the Morning Chronicle.

And in after years, contributing to the London Times at one period

or another as writers, were: Beaconsfield, Lord Chancellor
Brougham, Cardinal Newman, Lord Grey, Lord Macaulay, Sir William
Harcourt, Moore, Dean Stanley, Lord Sherbrook, and Dr. Groley.

The constant and consistent progress of the newspaper since its

feeble beginnings, and especially its development in the last two
hundred years, attest its importance to mankind. Rarely, indeed, has
progress been more deliberate; rarely has it been more substantial.
Long years of experience with it have tested and verified the
newspaper’s usefulness.

Thirst for news and for information has always prevailed and
newspaper progress undoubtedly must have taken a vigorous spurt
with the invention of type and printing but for the reason that both
church and state joined in its repression. In 1685, at the close of the
reign of King Charles II. there were in all England two newspapers
only, worthy of the name, and both of them were under the strict
supervision of the royal censor.

The first real jump in newspaper progress came with the

relaxation of government repression just after the year 1700. It was
then that Addison, Steele, Defoe, Fielding, Swift and Dr. Johnson,
gave the real beginnings to journalism. Thereafter, for a hundred
and fifty years, the advance and improvement in the making of
newspapers were deliberate and irresistible. From chatterers and
gossipers only the journals came gradually to be leaders of thought
and of public opinion and circulators of essential information. But the
change in them was so slow as to be almost unnoticed from year to
year.

In the latter half of the nineteenth century, however, came the

invention of the modern printing press which permits the printing of
a newspaper of thirty-five pages or more at the rate of thirty
thousand or more copies an hour; the invention of the stereotyping
process by which newspaper pages may be duplicated to indefinite
numbers, in solid metal, and used on an indefinite number of
presses in the printing of a single edition; and the invention of the
typesetting machine by which type may be cast and placed with
something like six times the speed of the old-time process of hand
composition. They were marvelous inventions.

These inventions removed mechanical difficulties that had

confined the size and restricted the circulation of newspapers, and
great changes came quickly. Heretofore the newspapers had been
restricted to eight pages and many of them printed four pages only;
but immediately twenty and twenty-four page editions appeared and
thirty-five and forty page ones are common now. This great increase
in volume permitted a like increase in scope and we now see in the
newspapers a mass of information on an innumerable number of
topics. Moreover, all changes in national or social life bring changes
in newspapers. Big business brought big newspapers, as soon as
they could be made.

Greatly increased newspaper importance has followed this

expansion. It is possible to present great events with a fullness of
detail and an attention to side issues hitherto unknown. A senator’s
attack on the Administration may be printed in full—six or seven
columns of it. An investigation involving the conduct of the war may
be reported question and answer verbatim. Pages are devoted to a
catastrophe like the blowing up of Halifax that a few years ago
would have been described in as many columns. Scores of special
articles are printed the like of which never had found place in the
daily newspaper. And in the evening sheets, especially, are
department features intended to interest women and children, funny
picture series, puzzles, medical information, screeds, and freak
features—all of which emphasize the very great change from
comparatively a few years ago. And every change from the
beginning has been in the direction of progress, has made the
newspaper a greater and a better product, has given to it the
increased confidence of the public. Confidence in a production of any
sort usually is withheld until experience has tested and verified it.
The value and the importance of the newspaper have come to be
firmly established.

Many persons do not require the services of a lawyer. Many rarely

employ a physician. Thousands seldom listen to a clergyman. But in
these wide-awake days everybody of any account must read the
newspaper, for the reading of the newspaper has come to be
absolutely essential to the daily routine of every intelligent person.
The things we read in the morning newspaper are the things we talk
about during the day. If you are interested in politics, or if you are
interested in finance, or the fluctuations of prices, or the movements
of society, or any phase of trade or commerce, or in any of the vital
questions of the hour—for all of these you turn to the newspaper.
The things taught in the colleges are the things of the past, or the
principles that experience has tested and verified. The things taught
by the newspapers are the things of the present. You cannot learn
politics from a textbook. You must absorb the politics of the day by a
study of the events of the day. Your financial policy must be
governed by existing monetary conditions rather than by conclusions
drawn from the panic of 1873 or that of 1907. The events of the day,
the progress of the day, are of more importance to the man in
business life or the man in social life than any other consideration.
The newspaper is his great source of inspiration and instruction. The
newspaper informs you, instructs you, influences you, amuses you,
inspires you, directs your thoughts, assists your conclusions, fires
your ambitions, enlarges your vocabulary—all of which are of the
utmost importance to you. It may be said, therefore, with confident
complacency that the profession of journalism rests on the solid
foundation of supplying an essential need.

In a lecture before the students of Dartmouth College, Mr. John

Lee Mahin said:

The family that pays a cent or two for its big morning
newspaper receives a carefully digested review of the political,
economic, social and commercial activities of the entire world
for the previous twenty-four hours. Probably five hundred men
in New York City would pay a thousand dollars a year each for
the commercial information alone that they receive from the
New York Times if they could not obtain it in any other way.

In considering these changes it should be remembered that the

journalism of fifty years ago was conspicuous for the reason that a
famous bunch of editors stamped their personality on almost every
column. It was the period of personal journalism. These editors were
inspired by the tragedies and the ferocities of the Civil War and by
the magnitude and the political importance of events involving as
they believed the very life of the nation. They were made
conspicuous by the very greatness of the causes that moved their
minds and their pens. They were stimulated to the limit of mental
exaltation in what they wrote. The country was surging with
excitement. Part of the people were clamoring for peace on any
terms. Others insisted on fighting the war to a finish at any cost of
life or money. Still others were for compromise. It is hardly possible
for generations of to-day to appreciate how intensely the war
agitated the people. The editors fought each other with a ferocity
otherwise unknown in American journalism. They were the people’s
champions and their names were known in every household; and
doubtless their names will live for years to come as the country’s
greatest editors.
 Nevertheless, let it be said, in all truth, that we have to-day scores
of editors equally capable of producing the crisp and pungent
paragraphs as well as the profound editorial articles of Prentice,
Greeley, Raymond, Dana, Bryant, Bowles, Watterson, Medill and
Manton Marble. The personal journalism of that day was impetuous
and impressive, but latterly and by degrees, in the big cities
especially, “the supreme importance of the editor has been
transformed into the supreme importance of the newspaper,” and we
hear less about the editor and more about the newspaper itself.

This effacement of individuality influences to exalt the newspaper

and to exalt journalism as a profession. The greatly enlarged field
has attracted thousands of most excellent writers, fine editors,
conductors, and managers. News-gathering and news-presentation
are now regarded as of supreme importance. Our pages bristle with
specialties. Our Sunday editions are magazines of information. The
great modern newspaper represents the product of the profession
rather than the genius of a single writer.

It was not so fifty years ago. These men, whose names have
come down to us, were great editorial writers rather than great
editors of the entire newspaper. Aside from the editorial page their
editions were devoid of genius. The news columns were slovenly in
appearance and dull in narration. They lacked the cunning of
embellishment with the flavor of literature and the charm of fiction.
The book reviews, the critical articles were excellent—but the editors
daubed dullness over everything else. The newspaper of that day is
not to be compared with the newspaper of to-day in general
excellence.

The editorial pages and the criticisms, however, were of high

excellence. It was a literary era and the literary impulse was a
conspicuous factor in public thought. Marble, Dana, Bryant, Curtis
and others made reputations for literary excellence in journalistic
work that would not to-day attract so much attention; for literary
excellence, while commended and appreciated, is not so much
insisted on, encouraged, or taught, as it was forty years ago.

The foreign correspondence of that day as printed in the

newspapers consisted largely of descriptions of scenery and
revelations of the writers’ emotions while climbing to Alpine heights
or floating by moonlight on the silent waters of Italian lakes. It was
written mostly by staff members who were on vacation trips and
who were inspired by the travel notes of Washington Irving and
Nathaniel Hawthorne that had obtained great attention. The journals
of fifty years ago did not maintain regular correspondents abroad. All
first class important papers to-day have representatives in the
capitals of Europe, but they do not write descriptions of scenery.
Some of the foreign correspondence of that day was very good,
however, notably that of Bayard Taylor for the New York Tribune.

The most conspicuous difference between the newspapers of 1850

or 1860 and those of to-day is in the treatment of news. Very little
space was given then to really important events. The national
convention that nominated a candidate for the presidency was
reported in two columns or so, whereas to-day from three to six
pages are required. A bare half column was given to the stock
market. The commercial markets were equally pinched; two or three
pages of matter are now devoted to them. There was no real estate
department. The court calendars were not printed for the lawyers,
nor the list of buyers in town for the merchants; nor was there a
sporting page, or a woman’s page, or a list of school teachers
appointed, or of policemen transferred, or of firemen granted a leave
of absence. The news was presented in the most perfunctory and
routine fashion, with no attempt to make it attractive or interesting.
News collecting had not been systematized or especially studied, as
to-day. The Associated Press was in its infancy, devoting itself almost
entirely to congress proceedings and to market reports. Raw
reporters were permitted to intersperse their own comments through
what they wrote and their conclusions received little revision or
supervision. Every line in the modern newspaper is revised by a copy
reader editor and not a suggestion of reportorial opinion is
permitted. The edition of fifty years ago was more or less subject to
haphazard inexactitude and casual error.

The present-day newspaper is prepared with great care. Its

ambitious articles are studied out. The errors in its news columns are
the results of haste rather than ignorance—the haste compelled by
necessity in getting to press on the minute. The Sunday edition
supplements, devoted to general topics and to literature, are already
taking the place of many kinds of literature. They print new fiction
by popular authors. They exploit and expand the latest
developments in science, art, music, medicine, mechanics,
construction, transportation—indeed, anything that is new or
important. They quickly transfer to their columns any important
matter contained in a new book.

The reading of newspapers is immeasurably greater than the

reading of any other kind of matter. The new book of which fifty
thousand copies are sold is called very successful, of which one
hundred thousand are sold is pronounced a wonder, of which two
hundred thousand are sold, phenomenal. Yet in New York City alone
a million and a half newspapers are printed every morning and
nearly two millions every afternoon. In America, millions of persons
who do not read more than five books in a year read a newspaper or
two every day.

And the newspaper of to-day is a better paper because it is more

accurate of statement and more faithful to fact, and more fair-
minded in the presentation of passing events. The long weary day of
misrepresentation in news reports is drawing to its close. The chief
events of the time are recorded with such fidelity to accuracy that in
future years they must be accepted as historically correct. All decent
newspapers now take pride in their accuracy of statement in the
news columns and there is little intentional misrepresentation. In our
political campaigns the attitude of each candidate is decently
described and what he says is faithfully reported and made equally
conspicuous. In this respect the newspapers have changed greatly
within a few years.

Moreover, the collection of news has been greatly facilitated by

increased telegraph and telephone and ocean cable efficiency. These
agents give much better transmission, making communication with
all parts of the world little short of instantaneous. Speaking of the
benefits to the world secured through electricity, Mr. W. W. Harris
said in a recent address:

When the Norsemen were on their way to the discovery of

America they had no compass; yet the compass had been
discovered by the Chinese many centuries before. But the news
of the compass had not in all these centuries gotten half way
around the world. And the science of navigation came not until
that piece of news had made its way to the European world. To-
day any important fact girdles the globe in a cable’s flash.

The newspapers of to-day are better because more study and

thought are put into their construction. Not only are the editorial
writers men of education, but the sub-editors, the night editors, the
revisers of copy and the reporters are mostly educated men—men
who have been taught where to seek and how to find information,
who have been taught to be confident and self-reliant and original.
The proportion of college-bred men on newspaper staffs is much
greater than it used to be, and the intelligence of the staffs has
increased in the same proportion. The modern newspaper wants
men of brains who know how to use their brains—men who can
think rapidly and act instantly.

This unceasing, irresistible, cumulative progress is making

newspapers more important, is making the profession of journalism
more attractive. Even as years of experience and study and laborious
patient application have perfected and solidified the practice of law
and medicine, have made firm and substantial the developments of
electricity and mechanics, and have solved the problems of
transportation and great business, so the making of newspapers is
settling down to a strong substantial basis.
 INDEX

Abbott, Lyman, 89
Acta Diurna, 197
Addison, Joseph, 89
Arnold, Sir Edward to Tennyson, 64

Barnato, Barnard, 110

Beecher, Henry Ward, 93, 173
Bowles, Samuel, 91, 148
Brisbane, Arthur, 174
Bryant, William Cullen, 147
Burleigh, Lord, 200
Butler, Samuel, 55
Butter, Nathaniel, 202

Cary, Henry N., 201

Cable, Costs, 107, 112, 190
Censorship, 164
Chaucer, 65
Christian Science Monitor, The, 89
City Editor, The, 2
Conquests, the public’s great interest in any
kind of a fight, 97
Copy Readers, 29, 35
Correspondent, the Washington, 10, 12
Correspondent, the Foreign, 112
Corbett, James, 97
Courant, The London, 205
Crooke, William, 18

Dana, Charles Anderson, his fine leadership, 48;

great as an editor, 61;
advice to his Managing Editor, 62;
on hasty editorial writing, 80;
on making the Sun talked about, 94
Dickens, Charles, experience as a reporter, 16

Edison, first public test of the household electric

light, 13
Editorial writer, The, 76, 78
Editorial council, The, 79
Editor in chief, The, 79
Editor, letters to, 80
Emerson, Ralph Waldo, 52
Exaggeration, where it may be tolerated, 70

Field, Eugene, 148

Field, William H., 194
Fiske, John, 181
Forney, Colonel John W., 35
Fourth Estate, The, 119
France, Anatole, 68
Froude, James Anthony, 148

Gazette, The Peking, 197

Gazette, The London, 206
George, Lloyd, 111
Gladden, Washington, 157
Gosse, Edmund, 56
Gray, 55
Greeley, Horace, 61, 91, 94, 147

Harris, W. W., 216

Hay, John, 148
Halsted, Murat, 148
Hearn, Lafcadio, 53, 55, 89, 172
Hearst, William R., 88
Heenan, John C., 97
Holmes, Oliver Wendell, 148
Howells, W. D., 148

Imitation, its repressive influence against a

writer’s advancement, 135
Irving, Washington, 65

Jefferson, Thomas, 148

Jenkins, how he got a job as reporter, 18
Johnson, Samuel, 56, 173
Journal, The New York, 101

Lauzanne, Stéphane, 149

Lee, James Melvin, 201
Lestrange, Roger, 206
Lincoln, Abraham, 159

Macaulay, T. B., 55, 71, 202

Machiavelli, 59
Mahin, John Lee, 211
Mail, London Daily, 185
Managing Editor, 46–49
Medill, Joseph, 148

Nelson, Colonel William Rockhill, 15

Newspaper, the modern, made with bewildering
speed, 43
Newspaper, the village, its opportunities for
community service, 130
Newspaper specialties, those embracing politics
and finance the most important, 180
Newspapers, indispensable to republican or
representative form of government. The
government speaks to the people through
them, 161
News, local, does not exist in New York City; all
important in the village, 140
Northcliffe, Lord, 173, 175

Observator, The, 206

Ochs, Adolph S., 91

Patriot, The Fulton, N. Y., 130

Pendleton, John, 12, 199
Policy, newspaper, its reversal is dangerous to
its prosperity, 91
Price, Charles W., 117
Proof reading, 40
Publications, technical and class, 119
Pulitzer, Joseph, 87

Quiller-Couch, Sir Arthur, 54, 158

Reid, Whitelaw, 94
Reporter, his beginnings and progress, 1–9;
the political, 8–10;
his unpleasant tasks, 22
Reporters, first announcements of great events
made by, 13
Review, The, 205
Roosevelt, Theodore, 31
Rossetti, 55

Sainte Beuve, 56
Saintsbury, George, 53
Salaries, newspaper, 146
Sayers, Tom, 97
Scott, Sir Walter, 55
Seitz, Don, 102
Sensationalism, wherein harmful, 103
Smith, Sidney, 70
Spectator, The, 205
Stead, William T., 67
Syndicate service, 138
System, 121
Sun, The Evening, 102

Talleyrand, 25
Tatler, The, 205, 206
Thackeray, William M., 174
Times, The New York, 91
Times, The London, 187
Titanic, steamship, loss of: how reported, 44
Tolstoy, 55
Tribune, The Chicago, 91
Tribune, The New York, 91

Victorian Literature, Era of, 83

Village, the American, its newspaper
opportunities, 132

War, its supreme interest to newspaper readers,

99
Weather, the: its importance and interest to the
reader, 100
Webster, Noah, 148
Wells, H. G., 17
West, Dean, 67
Whitman, Walt, 148
Whittier, John G., 148
Wilson, Woodrow, 58, 69, 159, 162
Writer, The, 60
 Transcriber’s Note:

Punctuation has been standardised. Spelling

and hyphenation have been retained as
published in the original publication except as
follows:

Page 3
everything happens in New York than
can changed to
everything happens in New York that
can
Page 47
or off Montauk Point: judgment
whether changed to
or off Montauk Point; judgment
whether
Page 60
better expresed by changed to
better expressed by
Page 89
kind to whom lacrimose emotion
changed to
kind to whom lachrymose emotion
Page 94
who succeded Greeley as editor
changed to
who succeeded Greeley as editor
Page 102
exaggeration and breathless
anouncement changed to
exaggeration and breathless
announcement
Page 111
opinion as to the propects for peace
changed to
opinion as to the prospects for peace
Page 198
sent as governor to Cilica changed to
sent as governor to Cilicia
Page 219
accounts the letters from Edinburg
changed to
accounts the letters from Edinburgh
Page 236
Gazette, The Pekin changed to
Gazette, The Peking
Page 220
Lausanne, Stéphane changed to
Lauzanne, Stéphane
*** END OF THE PROJECT GUTENBERG EBOOK THE YOUNG MAN
AND JOURNALISM ***

Updated editions will replace the previous one—the old editions

will be renamed.

Creating the works from print editions not protected by U.S.

copyright law means that no one owns a United States
copyright in these works, so the Foundation (and you!) can copy
and distribute it in the United States without permission and
without paying copyright royalties. Special rules, set forth in the
General Terms of Use part of this license, apply to copying and
distributing Project Gutenberg™ electronic works to protect the
PROJECT GUTENBERG™ concept and trademark. Project
Gutenberg is a registered trademark, and may not be used if
you charge for an eBook, except by following the terms of the
trademark license, including paying royalties for use of the
Project Gutenberg trademark. If you do not charge anything for
copies of this eBook, complying with the trademark license is
very easy. You may use this eBook for nearly any purpose such
as creation of derivative works, reports, performances and
research. Project Gutenberg eBooks may be modified and
printed and given away—you may do practically ANYTHING in
the United States with eBooks not protected by U.S. copyright
law. Redistribution is subject to the trademark license, especially
commercial redistribution.

START: FULL LICENSE

THE FULL PROJECT GUTENBERG LICENSE
 PLEASE READ THIS BEFORE YOU DISTRIBUTE OR USE THIS WORK

To protect the Project Gutenberg™ mission of promoting the

free distribution of electronic works, by using or distributing this
work (or any other work associated in any way with the phrase
“Project Gutenberg”), you agree to comply with all the terms of
the Full Project Gutenberg™ License available with this file or
online at www.gutenberg.org/license.

Section 1. General Terms of Use and

Redistributing Project Gutenberg™
electronic works
1.A. By reading or using any part of this Project Gutenberg™
electronic work, you indicate that you have read, understand,
agree to and accept all the terms of this license and intellectual
property (trademark/copyright) agreement. If you do not agree
to abide by all the terms of this agreement, you must cease
using and return or destroy all copies of Project Gutenberg™
electronic works in your possession. If you paid a fee for
obtaining a copy of or access to a Project Gutenberg™
electronic work and you do not agree to be bound by the terms
of this agreement, you may obtain a refund from the person or
entity to whom you paid the fee as set forth in paragraph 1.E.8.

1.B. “Project Gutenberg” is a registered trademark. It may only

be used on or associated in any way with an electronic work by
people who agree to be bound by the terms of this agreement.
There are a few things that you can do with most Project
Gutenberg™ electronic works even without complying with the
full terms of this agreement. See paragraph 1.C below. There
are a lot of things you can do with Project Gutenberg™
electronic works if you follow the terms of this agreement and
help preserve free future access to Project Gutenberg™
electronic works. See paragraph 1.E below.
1.C. The Project Gutenberg Literary Archive Foundation (“the
Foundation” or PGLAF), owns a compilation copyright in the
collection of Project Gutenberg™ electronic works. Nearly all the
individual works in the collection are in the public domain in the
United States. If an individual work is unprotected by copyright
law in the United States and you are located in the United
States, we do not claim a right to prevent you from copying,
distributing, performing, displaying or creating derivative works
based on the work as long as all references to Project
Gutenberg are removed. Of course, we hope that you will
support the Project Gutenberg™ mission of promoting free
access to electronic works by freely sharing Project Gutenberg™
works in compliance with the terms of this agreement for
keeping the Project Gutenberg™ name associated with the
work. You can easily comply with the terms of this agreement
by keeping this work in the same format with its attached full
Project Gutenberg™ License when you share it without charge
with others.

1.D. The copyright laws of the place where you are located also
govern what you can do with this work. Copyright laws in most
countries are in a constant state of change. If you are outside
the United States, check the laws of your country in addition to
the terms of this agreement before downloading, copying,
displaying, performing, distributing or creating derivative works
based on this work or any other Project Gutenberg™ work. The
Foundation makes no representations concerning the copyright
status of any work in any country other than the United States.

1.E. Unless you have removed all references to Project

Gutenberg:

1.E.1. The following sentence, with active links to, or other

immediate access to, the full Project Gutenberg™ License must
appear prominently whenever any copy of a Project
Gutenberg™ work (any work on which the phrase “Project
Welcome to our website – the perfect destination for book lovers and
knowledge seekers. We believe that every book holds a new world,
offering opportunities for learning, discovery, and personal growth.
That’s why we are dedicated to bringing you a diverse collection of
books, ranging from classic literature and specialized publications to
self-development guides and children's books.

More than just a book-buying platform, we strive to be a bridge

connecting you with timeless cultural and intellectual values. With an
elegant, user-friendly interface and a smart search system, you can
quickly find the books that best suit your interests. Additionally,
our special promotions and home delivery services help you save time
and fully enjoy the joy of reading.

Join us on a journey of knowledge exploration, passion nurturing, and

personal growth every day!

ebookmasss.com