This chapter is from the book

The Apache Derby Components

Developers, line of business (LOB) managers, and IT professionals have chosen
and will continue to choose the Apache Derby database in countless scenarios and
for numerous vertical applications. Apache Derby can be entirely embedded within
an application, used in a client/server architecture, or even embedded in an
application server.

Three major components are shipped with Apache Derby: the Apache Derby
database engine, the Apache Derby network server, and the Apache Derby
ij JDBC scripting tool (there are some other tools, but this is the
main one). As previously mentioned, the Apache Derby Network Client is a recent
IBM contribution that will become the mainstay for many of your applications
that leverage a traditional client/server environment. You can get it at:
http://incubator.apache.org/derby/faq.html#netclient.

The Apache Derby Database Engine

The core of an Apache Derby solution lies within the Apache Derby
database engine. As you have seen, the Apache Derby database engine is a
full-featured, fully functional, embeddable relational database engine. Having
been part of IBM for three years, the Apache Derby SQL dialect is a subset of
that used for DB2. This means that Apache Derby applications are, for the most
part, fully portable to DB2. In addition, an Apache Derby database can interact
with the DB2 Everyplace SyncServer (both as a client and as a backend data
store), which allows it to be part of a mobile solution that includes
synchronization logic.

Apache Derby can be easily embedded within a Java application because it is
implemented as a Java class library. For example, Apache Derby is usually
delivered as part of an application’s .JAR file in which the Apache Derby
.JAR file has been included.

The database is started when the Java virtual machine (JVM) that hosts the
application is started, and it is subsequently shut down when the JVM hosting
the application is terminated. Because a JVM can be multi-threaded, any threads
that are spawned within the JVM hosting the Apache Derby database engine can
access the database. Concurrent access to this database, without the use of the
Apache Derby network server, must be made from within the same JVM.

It is possible to have multiple JVMs running on a machine and even to have
separate Apache Derby databases in each JVM. In this case, the environments are
considered to be completely separate.

Apache Derby Network Server

The Apache Derby network server increases the reach of the Apache Derby
database engine by providing traditional client/server functionality across
JVMs, expanded data access interface options, as well as concurrent access
between JVMs on the same machine. The Apache Derby network server allows clients
to connect over TCP/IP.

When developers refer to Apache Derby as an embeddable database, they are
referring to the fact that the Apache Derby database runs within a JVM process.
Without the Apache Derby network server, there would be no networking services,
data access outside of the embedded JDBC driver in the database engine, or other
infrastructure requirements; this accounts for its small footprint.

Understanding what the embedded concept entails is critical when developing
applications. For example, one common misconception that developers have when
they work with Apache Derby as a standalone database is that it’s only a
single-user database and does not have communication capabilities. They believe
that it is a single-user, single-connection, single-threaded system and develop
their applications accordingly. This is not true. Apache Derby as a standalone
database can support as many connections as desired, so long as they are
established from the same JVM hosting the Apache Derby engine.

For an Apache Derby database to be accessed from a process that resides
outside the hosting JVM that loaded the Apache Derby database initially (even if
the JVM process resides on the same server), you need to load the Apache Derby
network server. Read that last sentence twice to ensure you understand it
because it is often a source of confusion for Apache Derby developers when
multiple JVMs reside on the same machine. The Apache Derby network server allows
for communications between JVM processes. This means that this communication
infrastructure isn’t solely required to communicate between machines; it
is needed even if two different JVM processes reside on the same
machine and want to talk to the same database.

Using the Apache Derby network server, you could have a number of Java
programs or JVMs interacting with a number of Apache Derby databases (or a
single database for that matter). The Apache Derby network server is also
required to support interfaces other than JDBC, like ODBC or .NET. The Apache
Derby database engine comes with an embedded JDBC driver (this is not the JCC
driver that we talked about earlier)—so you will not need the network
server for intra-JVM JDBC connections. The Apache Derby Network Client works
with the Apache Derby Network Server.

ij—The Apache Derby JDBC Scripting Tool

The ij tool is a JDBC-based scripting tool that allows SQL scripts
to be executed against an Apache Derby database. This is one of the few tools
used with Apache Derby. We will use this tool throughout the book to create a
database and some tables, populate those tables, and retrieve data from the
Apache Derby database.

It is important to remember the role of the Apache Derby network server when
using this tool because many application developers end up with a connection
error when using it for the first time. For example, let’s assume a
developer has created an application and is invoking that application to test
it. Starting the application starts a JVM where the application resides and
where the Apache Derby database engine runs. When testing the application, the
developer might want to add some data or work with the database schema, so what
better tool with which to connect to the database than the ij tool? If
you do not have the Apache Derby network server loaded, you are going to get an
error because the ij tool is a Java tool that runs in its own JVM. For
the most part, if you are a developer, we recommend that you include the Apache
Derby network server in your environment. Otherwise, you will have to concern
yourself with these sorts of issues, which can sneak up on you if your
integrated development environment (IDE) makes multiple connections to the
target database.