this section highlights the jdbc calls that make this specifically an embedded derby application the...

8/9/2019 This Section Highlights the JDBC Calls That Make This Specifically an Embedded Derby Application the Derby Netwo

1/22

When an application accesses a Derby database using the Embedded DerbyJDBC driver, the Derby engine does not run in a separate process, and thereare no separate database processes to start up and shut down. Instead, theDerby database engine runs inside the same Java Virtual Machine (JVM) as theapplication. So, Derby becomes part of the application just like any other jarfile that the application uses. Figure 1 depicts this embedded architecture.

Figure 1: Derby Embedded Architecture

This section shows how to compile and run a simple Java application using theDerby Embedded JDBC driver. The information presented is deliberately simple.For complete information, see the Derby Developer's Guide.

Set the environment

To set up the environment, follow the "Configure Embedded Derby"instructions.

Sample ApplicationCopy sample applicationThe Derby software includes a sample application called SimpleApp.java. InDerby 10.2 and above it is located in theDERBY_INSTALL/demo/programs/simple/ directory. (In Derby 10.1 it is locatedin the DERBY_INSTALL/demo/simple/ directory.) Copy that application intoyour current directory.

By default this application runs in embedded mode and does the following:

Starts up the Derby engineCreates and connects to a databaseCreates a tableInserts dataUpdates dataSelects dataDrops a table

DisconnectsShuts down DerbyA quick look at the codeThe SimpleApp.java application spends most of its time creating a table,inserting data into that table, and selecting the data back, demonstrating manyJDBC calls as it does so. This section highlights the JDBC calls that make thisspecifically an embedded Derby application. The "Derby Network Server"section shows how the same JDBC calls turn the same code into a client/serverapplication.

Load the Embedded JDBC DriverThe SimpleApp application loads the Derby Embedded JDBC driver and startsDerby up with this code:


2/22

public String driver = "org.apache.derby.jdbc.EmbeddedDriver";...Class.forName(driver).newInstance();Get an Embedded ConnectionThe SimpleApp application creates and connects to the derbyDB database with

this code:

public String protocol = "jdbc:derby:";...conn = DriverManager.getConnection(protocol + "derbyDB;create=true",props);That embedded connection URL, fully constructed, looks like this:

jdbc:derby:derbyDB;create=trueShut Derby downA clean shutdown performs a checkpoint and releases resources. If an

embedded application doesn't shut down Derby, a checkpoint won't beperformed. Nothing bad will happen; it just means that the next connectionwill be slower because Derby will run its recovery code.

Code to shut down a specific database looks like this:

DriverManager.getConnection("jdbc:derby:MyDbTest;shutdown=true");Code toshut down all databases and the Derby engine looks like this:

DriverManager.getConnection("jdbc:derby:;shutdown=true");The

SimpleApp.java code uses the second call to shut down all databases and theengine. You might also notice that it tests for a SQL exception. A cleanshutdown always throws SQL exception XJ015, which can be ignored.

Compile sample applicationCompile the sample application as shown below:

javac SimpleApp.javaYou can safely ignore any compile warnings that mightpop up.

Run sample applicationRun the sample application like this:

java SimpleAppYou should see the output shown below:

SimpleApp starting in embedded mode.Loaded the appropriate driver.Connected to and created database derbyDBCreated table derbyDBInserted 1956 Webster

Inserted 1910 UnionUpdated 1956 Webster to 180 GrandUpdated 180 Grand to 300 Lakeshore


3/22

Verified the rowsDropped table derbyDBClosed result set and statementCommitted transaction and closed connectionDatabase shut down normallySimpleApp finished

If instead you see an error like the one below, it means the class path is notcorrectly set:

java SimpleAppSimpleApp starting in embedded mode.exception thrown:

java.lang.ClassNotFoundException: org.apache.derby.jdbc.EmbeddedDriverat java.net.URLClassLoader$1.run(URLClassLoader.java:199)at java.security.AccessController.doPrivileged(Native Method)at java.net.URLClassLoader.findClass(URLClassLoader.java:187)

at java.lang.ClassLoader.loadClass(ClassLoader.java:289)at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:274)at java.lang.ClassLoader.loadClass(ClassLoader.java:235)at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:302)at java.lang.Class.forName0(Native Method)at java.lang.Class.forName(Class.java:141)at SimpleApp.go(SimpleApp.java:77)at SimpleApp.main(SimpleApp.java:61)

SimpleApp finished

For help resolving class path problems, see the "Configure Embedded Derby"and "Verify Derby" instructions.

Embedded Derby supports multiple users in one JVMDerby supports multiple connections to a given database. An example of an


4/22

embedded application that manages concurrent users is a Tomcat or Geronimoapplication server that embeds Derby. Any number of users can execute Webapplications that access a database through that Web server.

However, only one JVM may boot ("open") that database, so multipleapplications running in different JVMs cannot access the same database. To

understand this better, do the following.

The SimpleApp application created a database called derbyDB. In one windowconnect to this database with ij as shown below:

java org.apache.derby.tools.ijij version 10.4ij> connect 'jdbc:derby:derbyDB';ij>Now, in another window try to run your SimpleApp application:

java SimpleAppSimpleApp starting in embedded modeLoaded the appropriate driver

----- SQLException -----SQL State: XJ040Error Code: 40000Message: Failed to start database 'derbyDB', see the next exception for

details.

----- SQLException -----SQL State: XSDB6Error Code: 45000Message: Another instance of Derby may have already booted the database

C:\Apache\db-derby-10.4.1.3-bin\tutorial\derbyDB.SimpleApp finishedThe connection that SimpleApp tries to establish fails because anotherapplication, ij, is already connected to the derbyDB database.

The problem is ij and SimpleApp are running in different JVMs and a givendatabase can only be accessed from one JVM. The first application to connect"wins", in this case ij, and prevents other applications from connecting.

In fact, you can establish multiple connections to a given database fromdifferent JVMs. That's the topic of the next section, "Step 4: Derby NetworkServer".


5/22


6/22


7/22


8/22


9/22


10/22


11/22


12/22


13/22


14/22


15/22


16/22


17/22


18/22


19/22


20/22


21/22


22/22

this section highlights the jdbc calls that make this specifically an embedded derby application the...

Documents