# Class DatabaseConformanceSuite

java.lang.Object
com.codename1.testing.DatabaseConformanceSuite

public final class DatabaseConformanceSuite extends Object

The portable acceptance test for `com.codename1.db`.

One set of assertions, run unchanged on every platform. A port is conformant when this suite passes against it; there is no separate, per-platform notion of correct behaviour. It lives in the framework rather than in a test project so that the device suite, the simulator unit tests and anyone writing a new port can all run the same checks.

Failures are reported through a `Reporter` rather than thrown, so a single run reports every violation instead of stopping at the first. That matters most when bringing up a new port, where the useful output is the whole list.

    DatabaseConformanceSuite.runAll("conformance.db",
            DatabaseConformanceSuite.MODE_STRICT, myReporter);

##### Modes

`#MODE_STRICT` asserts the contract documented in the `com.codename1.db` package. `#MODE_LEGACY` asserts that `Database#setLegacyBehavior(boolean)` really does restore what each platform used to do, which is what makes the compatibility promise testable rather than aspirational. Run the legacy mode only with the flag actually set.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `DatabaseConformanceSuite.Reporter`
  Receives the outcome of each individual check.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `MODE_LEGACY`
  Assert that legacy compatibility mode restores the previous per-platform behaviour.
  `static final int`
  `MODE_STRICT`
  Assert the portable contract.
  `static final int`
  `PORT_ANDROID`
  The Android port.
  `static final int`
  `PORT_AUTODETECT`
  Not overridden; the port is read from the running `Display`.
  `static final int`
  `PORT_IOS`
  The iOS port, which has the most legacy behaviour to restore.
  `static final int`
  `PORT_OTHER`
  A port with no legacy behaviour of its own to restore.
  `static final int`
  `PORT_SIMULATOR`
  The simulator, whose `getPosition()` used to be 1-based.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `isDatabaseAvailable(DatabaseConformanceSuite.Reporter r)`
  Reports whether this platform provides a database at all.
  `static void`
  `runAll(String databaseName, int mode, DatabaseConformanceSuite.Reporter r)`
  Runs every group against a scratch database.
  `static void`
  `runCursor(Database db, int mode, DatabaseConformanceSuite.Reporter r)`
  Checks cursor navigation, positions, metadata and null reads.
  `static void`
  `runEncryption(String databaseName, int mode, DatabaseConformanceSuite.Reporter r)`
  Checks encrypted opens, the wrong-key path and the on-disk result.
  `static void`
  `runLifecycle(String databaseName, int mode, DatabaseConformanceSuite.Reporter r)`
  Checks opening, existence, deletion, paths and use-after-close.
  `static void`
  `runStatements(Database db, int mode, DatabaseConformanceSuite.Reporter r)`
  Checks statement execution, parameter binding and error reporting.
  `static void`
  `runTransactions(Database db, int mode, DatabaseConformanceSuite.Reporter r)`
  Checks commit, rollback and the flat transaction rules.
  `static void`
  `setPortKind(int portKind)`
  Declares which port the suite is being run against, for a harness with no `Display`.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### MODE_STRICT

    public static final int MODE_STRICT
    Assert the portable contract.
    See Also:
      - Constant Field Values

  - ### MODE_LEGACY

    public static final int MODE_LEGACY
    Assert that legacy compatibility mode restores the previous per-platform behaviour.
    See Also:
      - Constant Field Values

  - ### PORT_OTHER

    public static final int PORT_OTHER
    A port with no legacy behaviour of its own to restore.
    See Also:
      - Constant Field Values

  - ### PORT_SIMULATOR

    public static final int PORT_SIMULATOR
    The simulator, whose `getPosition()` used to be 1-based.
    See Also:
      - Constant Field Values

  - ### PORT_IOS

    public static final int PORT_IOS
    The iOS port, which has the most legacy behaviour to restore.
    See Also:
      - Constant Field Values

  - ### PORT_ANDROID

    public static final int PORT_ANDROID
    The Android port.
    See Also:
      - Constant Field Values

  - ### PORT_AUTODETECT

    public static final int PORT_AUTODETECT
    Not overridden; the port is read from the running `Display`.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### setPortKind

    public static void setPortKind(int portKind)

    Declares which port the suite is being run against, for a harness with no `Display`.

    Pass `#PORT_AUTODETECT` to go back to reading it from `Display`, which is what an on-device harness wants. This is global state, so a harness that sets it should reset it afterwards.

    ###### Parameters

    - `portKind`: one of the `PORT_` constants

  - ### runAll

    public static void runAll(String databaseName, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Runs every group against a scratch database.

    The database is created and deleted by this method, so pass a name the application does not otherwise use.

    ###### Parameters

    - `databaseName`: a scratch database name

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch database cannot be created at all
    Throws:
      `IOException`

  - ### isDatabaseAvailable

    public static boolean isDatabaseAvailable(DatabaseConformanceSuite.Reporter r)

    Reports whether this platform provides a database at all.

    Ports without an implementation return null from `Database#openOrCreate(java.lang.String)`. Callers use this to skip cleanly rather than fail.

    ###### Parameters

    - `r`: receives a skip message when there is no database

    ###### Returns

    true when a database can be opened

  - ### runLifecycle

    public static void runLifecycle(String databaseName, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Checks opening, existence, deletion, paths and use-after-close.

    ###### Parameters

    - `databaseName`: a scratch database name

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch database cannot be created
    Throws:
      `IOException`

  - ### runStatements

    public static void runStatements(Database db, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Checks statement execution, parameter binding and error reporting.

    ###### Parameters

    - `db`: an open database, left usable

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch table cannot be created
    Throws:
      `IOException`

  - ### runCursor

    public static void runCursor(Database db, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Checks cursor navigation, positions, metadata and null reads.

    ###### Parameters

    - `db`: an open database, left usable

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch table cannot be created
    Throws:
      `IOException`

  - ### runTransactions

    public static void runTransactions(Database db, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Checks commit, rollback and the flat transaction rules.

    ###### Parameters

    - `db`: an open database, left usable

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch table cannot be created
    Throws:
      `IOException`

  - ### runEncryption

    public static void runEncryption(String databaseName, int mode, DatabaseConformanceSuite.Reporter r) throws IOException

    Checks encrypted opens, the wrong-key path and the on-disk result.

    ###### Parameters

    - `databaseName`: a scratch database name, created and deleted here

    - `mode`: `#MODE_STRICT` or `#MODE_LEGACY`

    - `r`: receives the results

    ###### Throws

    - `IOException`: if the scratch database cannot be created
    Throws:
      `IOException`