Class DatabaseEncryptionException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.io.IOException

com.codename1.db.DatabaseEncryptionException

public class DatabaseEncryptionException
extends IOException

Thrown when an encrypted database cannot be opened, keyed or converted.

This extends java.io.IOException deliberately: every database method already declares IOException, so existing catch blocks keep compiling and keep working. Code that wants to tell the failure modes apart can catch this type and switch on #getErrorCode().

Example

try {
    db = Database.openOrCreate("secure.db", DatabaseConfig.passphrase(entered));
} catch (DatabaseEncryptionException err) {
    if (err.getErrorCode() == DatabaseEncryptionException.WRONG_KEY) {
        showRetryPrompt();
    } else {
        throw err;
    }
}

Field Summary

Fields

Modifier and Type	Field	Description
static final int	KEY_UNAVAILABLE	A managed key was requested but the platform key store could not produce or persist one.
static final int	MIGRATION_FAILED	Converting a database between encrypted and plaintext form failed part way through.
static final int	NOT_SUPPORTED	The platform cannot open encrypted databases at all.
static final int	WRONG_KEY	The supplied passphrase or key does not decrypt this database, or the file is not a database at all.

Constructor Summary

Constructors

Constructor	Description
DatabaseEncryptionException(int errorCode, String message)	Creates an exception with the given code and message.
DatabaseEncryptionException(int errorCode, String message, Throwable cause)	Creates an exception with the given code, message and underlying cause.

Method Summary

Modifier and Type	Method	Description
int	getErrorCode()	Returns the code identifying why the operation failed.

Methods inherited from class Throwable

addSuppressed, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, setStackTrace, toString

Methods inherited from class Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

NOT_SUPPORTED

public static final int NOT_SUPPORTED

The platform cannot open encrypted databases at all. Check Database#isEncryptionSupported() before offering encryption in the UI.

A request for encryption on such a platform always fails with this code. It never silently falls back to an unencrypted database.

See Also:

• Constant Field Values

WRONG_KEY

public static final int WRONG_KEY

The supplied passphrase or key does not decrypt this database, or the file is not a database at all. These two cases are indistinguishable by design: a correct cipher reveals nothing about a wrong key.

See Also:

• Constant Field Values

KEY_UNAVAILABLE

public static final int KEY_UNAVAILABLE

A managed key was requested but the platform key store could not produce or persist one. The database is not opened, because opening it unencrypted would silently downgrade the protection the caller asked for.

See Also:

• Constant Field Values

MIGRATION_FAILED

public static final int MIGRATION_FAILED

Converting a database between encrypted and plaintext form failed part way through. The original file is left untouched.

See Also:

• Constant Field Values

Constructor Details

DatabaseEncryptionException

public DatabaseEncryptionException(int errorCode,
 String message)

Creates an exception with the given code and message.

Parameters

• errorCode: one of the constants declared by this class

• message: a human readable description of the failure

DatabaseEncryptionException

public DatabaseEncryptionException(int errorCode,
 String message,
 Throwable cause)

Creates an exception with the given code, message and underlying cause.

Parameters

• errorCode: one of the constants declared by this class

• message: a human readable description of the failure

• cause: the underlying failure, retained for diagnostics

Method Details

getErrorCode

public int getErrorCode()

Returns the code identifying why the operation failed.

Returns

one of #NOT_SUPPORTED, #WRONG_KEY, #KEY_UNAVAILABLE or #MIGRATION_FAILED