DbDump (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je.util

## Class DbDump

- java.lang.Object
- - com.sleepycat.je.util.DbDump

- Direct Known Subclasses:
    DbScavenger

      public class DbDump
      extends Object

  Dump the contents of a database. This utility may be used programmatically or from the command line.

       java { com.sleepycat.je.util.DbDump |
              -jar je-<version>.jar DbDump }
         -h <dir>           # environment home directory
        [-f <fileName>]     # output file, for non -rR dumps
        [-l]                # list databases in the environment
        [-p]                # output printable characters
        [-r]                # salvage mode
        [-R]                # aggressive salvage mode
        [-d] <directory>    # directory for *.dump files (salvage mode)
        [-s <databaseName>] # database to dump
        [-v]                # verbose in salvage mode
        [-V]                # print JE version number

  See `main(java.lang.String[])` for a full description of the command line arguments.

  To dump a database to a stream from code:

          DbDump dump = new DbDump(env, databaseName, outputStream, boolean);
          dump.dump();

  Because a `DATA=END` marker is used to terminate the dump of each database, multiple databases can be dumped and loaded using a single stream. The `dump()` method leaves the stream positioned after the last line written and the `DbLoad.load()` method leaves the stream positioned after the last line read.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `dbName`
    `protected boolean` | `doAggressiveScavengerRun`
    `protected boolean` | `doScavengerRun`
    `protected Environment` | `env`
    `protected File` | `envHome`
    `protected boolean` | `formatUsingPrintable`
    `protected String` | `outputDirectory`
    `protected PrintStream` | `outputFile`
    `protected boolean` | `verbose`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DbDump(Environment env, String dbName, PrintStream outputFile, boolean formatUsingPrintable)` Create a DbDump object for a specific environment and database.
    `DbDump(Environment env, String dbName, PrintStream outputFile, String outputDirectory, boolean formatUsingPrintable)` Deprecated. Please use the 4-arg ctor without outputDirectory instead.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `dump()` Perform the dump.
    `protected void` | `dumpOne(PrintStream o, byte[] ba, boolean formatUsingPrintable)`
    `static void` | `main(String[] argv)` The main used by the DbDump utility.
    `protected void` | `openEnv(boolean doRecovery)`
    `protected boolean` | `parseArgs(String[] argv)`
    `protected void` | `printHeader(PrintStream o, boolean dupSort, boolean formatUsingPrintable)`
    `protected void` | `printUsage(String msg)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### envHome

          protected File envHome

    - #### env

          protected Environment env

    - #### dbName

          protected String dbName

    - #### formatUsingPrintable

          protected boolean formatUsingPrintable

    - #### outputDirectory

          protected String outputDirectory

    - #### outputFile

          protected PrintStream outputFile

    - #### doScavengerRun

          protected boolean doScavengerRun

    - #### doAggressiveScavengerRun

          protected boolean doAggressiveScavengerRun

    - #### verbose

          protected boolean verbose

  - ### Constructor Detail

    - #### DbDump

          @Deprecated
          public DbDump(Environment env,
                           String dbName,
                           PrintStream outputFile,
                           String outputDirectory,
                           boolean formatUsingPrintable)

      Deprecated. Please use the 4-arg ctor without outputDirectory instead.

    - #### DbDump

          public DbDump(Environment env,
                String dbName,
                PrintStream outputFile,
                boolean formatUsingPrintable)

      Create a DbDump object for a specific environment and database.
      Parameters:
        `env` - The Environment containing the database to dump.
        `dbName` - The name of the database to dump.
        `outputFile` - The output stream to dump the database to.
        `formatUsingPrintable` - true if the dump should use printable characters.

  - ### Method Detail

    - #### main

          public static void main(String[] argv)
                           throws Exception

      The main used by the DbDump utility.
      Parameters:
        `argv` - The arguments accepted by the DbDump utility.

             usage: java { com.sleepycat.je.util.DbDump | -jar
             je-<version>.jar DbDump }
                         [-f output-file] [-l] [-p] [-V]
                         [-s database] -h dbEnvHome [-rR] [-v]
                         [-d directory]

        -f - the file to dump to. If omitted, output is to System.out. Does not apply when -r or -R is used.
        -l - list the databases in the environment.
        -p - output printable characters.
          If characters in either the key or data items are printing characters (as defined by isprint(3)), use printing characters in file to represent them. This option permits users to use standard text editors and tools to modify the contents of databases.
        -V - display the version of the JE library.
        -s database - the database to dump. Does not apply when -r or -R is used.
        -h dbEnvHome - the directory containing the database environment.
        -d directory - the output directory for *.dump files. Applies only when -r or -R is used.
        -v - print progress information to stdout for -r or -R mode.
        -r - Salvage data from possibly corrupt data files.
          The records for all databases are output. The records for each database are saved into <databaseName>.dump files in the current directory.

          This option recreates the Btree structure in memory, so as large a heap size as possible should be specified. If -r cannot be used due to insufficient memory, use -R instead.

          When used on uncorrupted data files, this option should return equivalent data to a normal dump, but most likely in a different order; in other words, it should output a transactionally correct data set. However, there is one exception where not all committed records will be output:

          - When a committed transaction spans more than one .jdb file, and the last file in this set of files has been deleted by the log cleaner but earlier files have not, records for that transaction that appear in the earlier files will not be output. This is because the Commit entry in the last file is missing, and DbDump believes that the transaction was not committed. Such missing output should be relatively rare. Note that records in deleted files will be output, because they were migrated forward by the log cleaner and are no longer associated with a transaction.
        -R - Aggressively salvage data from a possibly corrupt file.

          The records for all databases are output. The records for each database are saved into <databaseName>.dump files in the current directory.

          Unlike -r, the -R option does not recreate the Btree structure in memory. However, it does use a bit set to track all committed transactions, so as large a heap size as possible should be specified.

          -R also differs from -r in that -R does not return a transactionally correct data set. This is because the Btree information is not reconstructed in memory. Therefore, data dumped in this fashion will almost certainly have to be edited by hand or other means before or after the data is reloaded. Be aware of the following abnormalities.

          - Deleted records are often output. An application specific technique should normally be used to correct for this.
          - Multiple versions of the same record are sometimes output. When this happens, the more recent version of a record is output first. Therefore, the -n option should normally be used when running DbLoad.
          - When a committed transaction spans more than one .jdb file, and the last file in this set of files has been deleted by the log cleaner but earlier files have not, records for that transaction that appear in the earlier files will not be output. This is because the Commit entry in the last file is missing, and DbDump believes that the transaction was not committed. Such missing output should be relatively rare. Note that records in deleted files will be output, because they were migrated forward by the log cleaner and are no longer associated with a transaction. (This abnormality also occurs with -r.)
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `Exception`

    - #### printUsage

          protected void printUsage(String msg)

    - #### parseArgs

          protected boolean parseArgs(String[] argv)
                               throws IOException

      Throws:
        `IOException`

    - #### openEnv

          protected void openEnv(boolean doRecovery)
                          throws EnvironmentNotFoundException,
                                 EnvironmentLockedException

      Throws:
        `EnvironmentNotFoundException`
        `EnvironmentLockedException`

    - #### dump

          public void dump()
                    throws EnvironmentNotFoundException,
                           EnvironmentLockedException,
                           DatabaseNotFoundException,
                           IOException

      Perform the dump.
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IOException` - in subclasses.
        `EnvironmentNotFoundException`
        `EnvironmentLockedException`
        `DatabaseNotFoundException`

    - #### printHeader

          protected void printHeader(PrintStream o,
                         boolean dupSort,
                         boolean formatUsingPrintable)

    - #### dumpOne

          protected void dumpOne(PrintStream o,
                     byte[] ba,
                     boolean formatUsingPrintable)

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.