gsg/JAVA/javaindexusage.html

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Secondary Database Example</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
    <link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
    <link rel="up" href="indexes.html" title="Chapter��10.��Secondary Databases" />
    <link rel="previous" href="joins.html" title="Database Joins" />
    <link rel="next" href="dbconfig.html" title="Chapter��11.��Database Configuration" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Secondary Database Example</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="joins.html">Prev</a>��</td>
          <th width="60%" align="center">Chapter��10.��Secondary Databases</th>
          <td width="20%" align="right">��<a accesskey="n" href="dbconfig.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="javaindexusage"></a>Secondary Database Example</h2>
          </div>
        </div>
        <div></div>
      </div>
      <p>In previous chapters in this book, we built applications that load
    and display several DB databases. In this example, we will extend those
    examples to use secondary databases. Specifically:</p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>In <a href="dbtJavaUsage.html#dbsStoredClass">Stored Class Catalog Management with MyDbs</a> we built a
        class that we can use to open several <tt class="classname">Database</tt> objects.
        In <a href="javaindexusage.html#secondaryMyDbs">Opening Secondary Databases with MyDbs</a> we will extend
        that class to also open and manage a <tt class="classname">SecondaryDatabase</tt>.
        </p>
          </li>
          <li>
            <p>In <a href="cursorJavaUsage.html">Cursor Example</a> we
        built an application to display our inventory database (and related
        vendor information). In <a href="javaindexusage.html#exampleReadJavaSecondaries">Using Secondary Databases with ExampleDatabaseRead</a> we will extend that application to
        show inventory records based on the index we cause to be loaded using
        <tt class="classname">ExampleDatabaseLoad</tt>.
        </p>
          </li>
        </ul>
      </div>
      <p>
            Before we can use a secondary database, we must implement a class to extract secondary keys for us.
            We use <tt class="classname">ItemNameKeyCreator</tt> for this purpose.
        </p>
      <div class="example">
        <a id="ItemNameKeyCreator-Java"></a>
        <p class="title">
          <b>Example 10.1 ItemNameKeyCreator.java</b>
        </p>
        <p>
        This class assumes the primary database
        uses <tt class="classname">Inventory</tt> objects for the record data. The
        <tt class="classname">Inventory</tt> class is described in <a href="dbtJavaUsage.html#inventoryjava">Inventory.java</a>.</p>
        <p>In our key creator class, we make use of a custom tuple binding
        called <tt class="classname">InventoryBinding</tt>. This class is described in <a href="dbtJavaUsage.html#InventoryJavaBinding">InventoryBinding.java</a>.</p>
        <p>You can find <tt class="filename">InventoryBinding.java</tt> in: </p>
        <pre class="programlisting"><span class="emphasis"><em>DB_INSTALL</em></span>/examples_java/db/GettingStarted</pre>
        <p>
        where <tt class="literal"><span class="emphasis"><em>DB_INSTALL</em></span></tt> is the location where you
        placed your DB distribution.
    </p>
        <a id="java_index11"></a>
        <pre class="programlisting">package db.GettingStarted;

import com.sleepycat.db.DatabaseEntry;
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.SecondaryDatabase;
import com.sleepycat.db.SecondaryKeyCreator;
import com.sleepycat.bind.tuple.TupleBinding;

import java.io.IOException;

public class ItemNameKeyCreator implements SecondaryKeyCreator {

    private TupleBinding theBinding;

    // Use the constructor to set the tuple binding
    ItemNameKeyCreator(TupleBinding binding) {
        theBinding = binding;
    }

    // Abstract method that we must implement
    public boolean createSecondaryKey(SecondaryDatabase secDb,
        DatabaseEntry keyEntry,    // From the primary
        DatabaseEntry dataEntry,   // From the primary
        DatabaseEntry resultEntry) // set the key data on this.
        throws DatabaseException {

        try {
            // Convert dataEntry to an Inventory object
            Inventory inventoryItem =
                (Inventory) theBinding.entryToObject(dataEntry);
            // Get the item name and use that as the key
            String theItem = inventoryItem.getItemName();
            resultEntry.setData(theItem.getBytes("UTF-8"));
        } catch (IOException willNeverOccur) {}

        return true;
    }
} </pre>
      </div>
      <p>
            Now that we have a key creator, we can use it to generate keys for a
            secondary database. We will now extend <tt class="classname">MyDbs</tt>
            to manage a secondary database, and to use
            <tt class="classname">ItemNameKeyCreator</tt> to generate keys for that
            secondary database.
      </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="secondaryMyDbs"></a>Opening Secondary Databases with MyDbs</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>In <a href="dbtJavaUsage.html#dbsStoredClass">Stored Class Catalog Management with MyDbs</a> we built
      <tt class="classname">MyDbs</tt> as an example of a class that
      encapsulates
      <tt class="classname">Database</tt> opens and closes. We will now extend
      that class to manage a <tt class="classname">SecondaryDatabase</tt>.</p>
        <div class="example">
          <a id="mydbsSecondary"></a>
          <p class="title">
            <b>Example 10.2 SecondaryDatabase Management with MyDbs</b>
          </p>
          <p>
            We start by importing two additional classes needed to support secondary databases.
            We also add a global variable to use as a handle for our secondary database.
        </p>
          <a id="java_index12"></a>
          <pre class="programlisting">// File MyDbs.java
package db.GettingStarted;

import java.io.FileNotFoundException;

import com.sleepycat.bind.serial.StoredClassCatalog;
import com.sleepycat.bind.tuple.TupleBinding;
import com.sleepycat.db.Database;
import com.sleepycat.db.DatabaseConfig;
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.DatabaseType;
<b class="userinput"><tt>import com.sleepycat.db.SecondaryConfig;
import com.sleepycat.db.SecondaryDatabase;</tt></b>

public class MyDbs {

    // The databases that our application uses
    private Database vendorDb = null;
    private Database inventoryDb = null;
    private Database classCatalogDb = null;
    <b class="userinput"><tt>private SecondaryDatabase itemNameIndexDb = null;</tt></b>

    private String vendordb = "VendorDB.db";
    private String inventorydb = "InventoryDB.db";
    private String classcatalogdb = "ClassCatalogDB.db";
    <b class="userinput"><tt>private String itemnameindexdb = "ItemNameIndexDB.db";</tt></b>

    // Needed for object serialization
    private StoredClassCatalog classCatalog;

    // Our constructor does nothing
    public MyDbs() {} </pre>
          <p>
        Next we update the <tt class="methodname">MyDbs.setup()</tt> method to open the
		secondary database. As a part of this, we have to pass an
		<tt class="classname">ItemNameKeyCreator</tt> object on the call to open the secondary
        database. Also, in order to instantiate <tt class="classname">ItemNameKeyCreator</tt>, we need an
        <tt class="classname">InventoryBinding</tt> object (we described this class in
            <a href="dbtJavaUsage.html#InventoryJavaBinding">InventoryBinding.java</a>).
        We do all this work together inside of <tt class="methodname">MyDbs.setup()</tt>.
    </p>
          <a id="java_index13"></a>
          <pre class="programlisting">    public void setup(String databasesHome)
        throws DatabaseException {
        DatabaseConfig myDbConfig = new DatabaseConfig();
        <b class="userinput"><tt>SecondaryConfig mySecConfig = new SecondaryConfig();</tt></b>

        myDbConfig.setErrorStream(System.err);
        <b class="userinput"><tt>mySecConfig.setErrorStream(System.err);</tt></b>
        myDbConfig.setErrorPrefix("MyDbs");
        <b class="userinput"><tt>mySecConfig.setErrorPrefix("MyDbs");</tt></b>
        myDbConfig.setType(DatabaseType.BTREE);
        <b class="userinput"><tt>mySecConfig.setType(DatabaseType.BTREE);</tt></b>
        myDbConfig.setAllowCreate(true);
        <b class="userinput"><tt>mySecConfig.setAllowCreate(true);</tt></b>

        // Now open, or create and open, our databases
        // Open the vendors and inventory databases
        try {
            vendordb = databasesHome + "/" + vendordb;
            vendorDb = new Database(vendordb,
                                    null,
                                    myDbConfig);

            inventorydb = databasesHome + "/" + inventorydb;
            inventoryDb = new Database(inventorydb,
                                        null,
                                        myDbConfig);

            // Open the class catalog db. This is used to
            // optimize class serialization.
            classcatalogdb = databasesHome + "/" + classcatalogdb;
            classCatalogDb = new Database(classcatalogdb,
                                          null,
                                          myDbConfig);
        } catch(FileNotFoundException fnfe) {
            System.err.println("MyDbs: " + fnfe.toString());
            System.exit(-1);
        }

        // Create our class catalog
        classCatalog = new StoredClassCatalog(classCatalogDb);

        // Need a tuple binding for the Inventory class.
        // We use the InventoryBinding class
        // that we implemented for this purpose.
        TupleBinding inventoryBinding = new InventoryBinding();

        <b class="userinput"><tt>// Open the secondary database. We use this to create a
        // secondary index for the inventory database

        // We want to maintain an index for the inventory entries based
        // on the item name. So, instantiate the appropriate key creator
        // and open a secondary database.
        ItemNameKeyCreator keyCreator =
            new ItemNameKeyCreator(new InventoryBinding());

        // Set up additional secondary properties
        // Need to allow duplicates for our secondary database
        mySecConfig.setSortedDuplicates(true);
        mySecConfig.setAllowPopulate(true); // Allow autopopulate
        mySecConfig.setKeyCreator(keyCreator);
        // Now open it
        try {
            itemnameindexdb = databasesHome + "/" + itemnameindexdb;
            itemNameIndexDb = new SecondaryDatabase(itemnameindexdb,
                                                    null,
                                                    inventoryDb,
                                                    mySecConfig);
        } catch(FileNotFoundException fnfe) {
            System.err.println("MyDbs: " + fnfe.toString());
            System.exit(-1);
        }</tt></b>
    }
    </pre>
          <p>
        Next we need an additional getter method for returning the secondary database.
    </p>
          <a id="java_index14"></a>
          <pre class="programlisting">    public SecondaryDatabase getNameIndexDB() {
        return itemNameIndexDb;
    } </pre>
          <p>Finally, we need to update the <tt class="methodname">MyDbs.close()</tt>
        method to close the new secondary database. We want to make sure that
        the secondary is closed before the primaries. While
        this is not necessary for this example because our
        closes are single-threaded, it is still a good habit to adopt.</p>
          <a id="java_index15"></a>
          <pre class="programlisting">    public void close() {
        try {
            <b class="userinput"><tt>if (itemNameIndexDb != null) {
                itemNameIndexDb.close();
            }</tt></b>

            if (vendorDb != null) {
                vendorDb.close();
            }

            if (inventoryDb != null) {
                inventoryDb.close();
            }

            if (classCatalogDb != null) {
                classCatalogDb.close();
            }

        } catch(DatabaseException dbe) {
            System.err.println("Error closing MyDbs: " +
                                dbe.toString());
            System.exit(-1);
        }
    }
} </pre>
          <p>That completes our update to <tt class="classname">MyDbs</tt>. You
        can find the complete class implementation in:
        </p>
          <pre class="programlisting"><span class="emphasis"><em>DB_INSTALL</em></span>/examples_java/db/GettingStarted</pre>
          <p>
        where <tt class="literal"><span class="emphasis"><em>DB_INSTALL</em></span></tt> is the location where you
        placed your DB distribution.
    </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="exampleReadJavaSecondaries"></a>Using Secondary Databases with ExampleDatabaseRead</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>Because we performed all our secondary database configuration management in
        <tt class="classname">MyDbs</tt>, we do not need to modify <tt class="classname">ExampleDatabaseLoad</tt> at all in
        order to create our secondary indices. When <tt class="classname">ExampleDatabaseLoad</tt> calls
        <tt class="methodname">MyDbs.setup()</tt>, all of the necessary work is performed for us.
        </p>
        <p>
            However, we still need to take advantage of the new secondary indices. We do this by updating
            <tt class="classname">ExampleDatabaseRead</tt> to allow us to query for an inventory record based on its name.
            Remember that the primary key for an inventory record is the item's SKU. The item's name is contained in the
            <tt class="classname">Inventory</tt> object that is stored as each record's data in the inventory database. But
            our new secondary index now allows us to easily query based on the item's name.
        </p>
        <p>
        For this update, we modify
        <tt class="classname">ExampleDatabaseRead</tt> to accept a new command line switch,
        <tt class="literal">-s</tt>, whose argument is the name of an inventory item.
        If the switch is present on the command line call to
        <tt class="classname">ExampleDatabaseRead</tt>, then the application will
        use the secondary database to look up and display all the inventory
        records with that item name. Note that we use a <tt class="classname">SecondaryCursor</tt>
        to seek to the item name key and then display all matching records.
      </p>
        <p>Remember that you can find <tt class="filename">ExampleDatabaseRead.java</tt> in: </p>
        <pre class="programlisting"><span class="emphasis"><em>DB_INSTALL</em></span>/examples_java/db/GettingStarted</pre>
        <p>
        where <tt class="literal"><span class="emphasis"><em>DB_INSTALL</em></span></tt> is the location where you
        placed your DB distribution.
    </p>
        <div class="example">
          <a id="secondaryWithEDR"></a>
          <p class="title">
            <b>Example 10.3 SecondaryDatabase usage with ExampleDatabaseRead</b>
          </p>
          <p>
            First we need to import an additional class in order to use the secondary cursor:
        </p>
          <a id="java_index16"></a>
          <pre class="programlisting">package db.GettingStarted;

import java.io.IOException;

import com.sleepycat.bind.EntryBinding;
import com.sleepycat.bind.serial.SerialBinding;
import com.sleepycat.bind.tuple.TupleBinding;
import com.sleepycat.db.Cursor;
import com.sleepycat.db.DatabaseEntry;
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.LockMode;
import com.sleepycat.db.OperationStatus;
<b class="userinput"><tt>import com.sleepycat.db.SecondaryCursor;</tt></b> </pre>
          <p>Next we add a single global variable:</p>
          <a id="java_index17"></a>
          <pre class="programlisting">    public class ExampleDatabaseRead {

    private static String myDbsPath = "./";

    // Encapsulates the database environment and databases.
    private static MyDbs myDbs = new MyDbs();

    private static TupleBinding inventoryBinding;
    private static EntryBinding vendorBinding;

    <b class="userinput"><tt>// The item to locate if the -s switch is used
    private static String locateItem;</tt></b> </pre>
          <p>Next we update <tt class="methodname">ExampleDatabaseRead.run()</tt> to
        check to see if the <tt class="literal">locateItem</tt> global variable has a
        value. If it does, then we show just those records related to the item
        name passed on the <tt class="literal">-s</tt> switch.</p>
          <a id="java_index18"></a>
          <pre class="programlisting">    private void run(String args[])
        throws DatabaseException {
        // Parse the arguments list
        parseArgs(args);

        myDbs.setup(myDbsPath);

        // Setup our bindings.
        inventoryBinding = new InventoryBinding();
        vendorBinding =
             new SerialBinding(myDbs.getClassCatalog(),
                               Vendor.class);

            <b class="userinput"><tt>if (locateItem != null) {
                showItem();
            } else {</tt></b>
                showAllInventory();
            <b class="userinput"><tt>}</tt></b>
    } </pre>
          <p>
            Finally, we need to implement <tt class="methodname">ExampleDatabaseRead.showItem()</tt>.
            This is a fairly simple method that opens a secondary cursor,
            and then displays every primary record that is related to the secondary
            key identified by the <tt class="literal">locateItem</tt> global variable.
        </p>
          <a id="java_index19"></a>
          <pre class="programlisting">    private void showItem() throws DatabaseException {
        SecondaryCursor secCursor = null;
        try {
            // searchKey is the key that we want to find in the
            // secondary db.
            DatabaseEntry searchKey =
                new DatabaseEntry(locateItem.getBytes("UTF-8"));

            // foundKey and foundData are populated from the primary
            // entry that is associated with the secondary db key.
            DatabaseEntry foundKey = new DatabaseEntry();
            DatabaseEntry foundData = new DatabaseEntry();

            // open a secondary cursor
            secCursor =
                myDbs.getNameIndexDB().openSecondaryCursor(null, null);

            // Search for the secondary database entry.
            OperationStatus retVal =
                secCursor.getSearchKey(searchKey, foundKey,
                    foundData, LockMode.DEFAULT);

            // Display the entry, if one is found. Repeat until no more
            // secondary duplicate entries are found
            while(retVal == OperationStatus.SUCCESS) {
                Inventory theInventory =
                    (Inventory)inventoryBinding.entryToObject(foundData);
                displayInventoryRecord(foundKey, theInventory);
                retVal = secCursor.getNextDup(searchKey, foundKey,
                    foundData, LockMode.DEFAULT);
            }
        } catch (Exception e) {
            System.err.println("Error on inventory secondary cursor:");
            System.err.println(e.toString());
            e.printStackTrace();
        } finally {
            if (secCursor != null) {
                secCursor.close();
            }
        }

    }</pre>
          <p>The only other thing left to do is to update
        <tt class="methodname">ExampleDatabaseRead.parseArgs()</tt> to support the <tt class="literal">-s</tt> command
        line switch. To see how this is done, see
        <tt class="filename">ExampleDatabaseRead.java</tt> in:
        </p>
          <pre class="programlisting"><span class="emphasis"><em>DB_INSTALL</em></span>/examples_java/db/GettingStarted</pre>
          <p>
        where <tt class="literal"><span class="emphasis"><em>DB_INSTALL</em></span></tt> is the location where you
        placed your DB distribution.
    </p>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="joins.html">Prev</a>��</td>
          <td width="20%" align="center">
            <a accesskey="u" href="indexes.html">Up</a>
          </td>
          <td width="40%" align="right">��<a accesskey="n" href="dbconfig.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Database Joins��</td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top">��Chapter��11.��Database Configuration</td>
        </tr>
      </table>
    </div>
  </body>
</html>