org.cruxframework.crux.core.client.db

Interface Database

All Known Implementing Classes:

AbstractDatabase, IDXAbstractDatabase, WSQLAbstractDatabase

public interface Database

A Crux client database. Uses IndexedDB (http://www.w3.org/TR/IndexedDB/) like interface to store objects on application's client side. To declare a new database, create a new interface extending Database and use DatabaseDef annotation on it to specify database structure.

See the following example:

 @DatabaseDef(name="CruxCompanyDatabase", version=1, defaultErrorHandler=CompanyDatabase.ErrorHandler.class, 
              objectStores={@DatabaseDef.ObjectStoreDef(targetClass=Person.class)})
 public interface CompanyDatabase extends Database{
   public static class ErrorHandler implements DatabaseErrorHandler {
     @Override
     public void onError(String message) {
        Crux.getErrorHandler().handleError(message);
     }
     @Override
     public void onError(String message, Throwable t) {
        Crux.getErrorHandler().handleError(message, t);
     }
   }
 }
 

To use the database, just call GWT.create on the given interface, or inject it on your class.

 public class MyController {
    @Inject
    private CompanyDatabase database;
    
    @Expose
    public void myMethod() {
       database.open(new DatabaseCallback(){
         public void onSuccess(){
            Window.alert("database ready for use");
         }
       });
    }
 }
 

Author:

Thiago da Rosa de Bustamante

Method Summary

Methods

Modifier and Type	Method and Description
<V> void	add(V[] objects, String objectStore, DatabaseCallback callback) Insert all objects into its associated objectStore.
void	close() Close the current database.
void	delete(DatabaseCallback callback) Remove the current database from client browser.
<K> void	delete(KeyRange<K> keyRange, String objectStore, DatabaseCallback callback) Remove all objects in the given range from its associated objectStore.
<K> void	delete(K key, String objectStore, DatabaseCallback callback) Remove the object associated with the given key from its associated objectStore.
<K,V> void	get(K key, String objectStore, DatabaseRetrieveCallback<V> callback) Retrieve the object associated with the given key from its associated objectStore.
String	getName() Retrieve the database name.
Transaction	getTransaction(String[] storeNames, Transaction.Mode mode) Create a new transaction targeting the given objectStores.
Transaction	getTransaction(String[] storeNames, Transaction.Mode mode, Transaction.TransactionCallback callback) Create a new transaction targeting the given objectStores.
int	getVersion() Retrieve the database version.
boolean	isOpen() Return true if the current database is open.
boolean	isSupported() Return true if Crux Database is supported by current browser.
void	open(DatabaseCallback callback) Open the database.
<V> void	put(V[] objects, String objectStore, DatabaseCallback callback) Update all received objects into its associated objectStore.
void	setDefaultErrorHandler(DatabaseErrorHandler errorHandler) Sets an error handler to be called to handle uncaught errors.
void	setName(String newName) Change the database name.
void	setVersion(int newVersion) Change the database version.
void	useIndexedDB() Forces Crux to use Indexed DB implementation for its database.
void	useWebSQL() Forces Crux to use WEB SQL implementation for its database.

Method Detail

isOpen

boolean isOpen()

Return true if the current database is open.

Returns:

true if open

getName

String getName()

Retrieve the database name. This information is extracted from @DatabaseDef annotation

Returns:

database name

setName

void setName(String newName)
             throws DatabaseException

Change the database name. This operation can not be executed on an open database.

Parameters:

newName - new database name

Throws:

DatabaseException

setVersion

void setVersion(int newVersion)
                throws DatabaseException

Change the database version. This operation can not be executed on an open database.

Parameters:

newVersion - new database version

Throws:

DatabaseException

getVersion

int getVersion()

Retrieve the database version. This information is extracted from @DatabaseDef annotation

Returns:

database version

open

void open(DatabaseCallback callback)

Open the database. If it does not exists, create a new database.

Parameters:

callback - called when operation is completed

close

void close()

Close the current database.

delete

void delete(DatabaseCallback callback)

Remove the current database from client browser.

Parameters:

callback - called when operation is completed

getTransaction

Transaction getTransaction(String[] storeNames,
                         Transaction.Mode mode)

Create a new transaction targeting the given objectStores.

Parameters:

storeNames - stores referenced by the transaction. You can not use any object store inside your transaction if it is not listed here.

mode - transaction mode. See Mode for available modes

Returns:

the transaction

getTransaction

Transaction getTransaction(String[] storeNames,
                         Transaction.Mode mode,
                         Transaction.TransactionCallback callback)

Create a new transaction targeting the given objectStores. If an unknown object store is informed, a DatabaseException is threw

Parameters:

storeNames - stores referenced by the transaction. You can not use any object store inside your transaction if it is not listed here.

mode - transaction mode. See Mode for available modes

callback - called when operation is completed

Returns:

the transaction

Throws:

DatabaseException - if an unknown object store is informed

add

<V> void add(V[] objects,
           String objectStore,
           DatabaseCallback callback)

Insert all objects into its associated objectStore. If no objectStore is associated with object informed, a DatabaseException is threw

Type Parameters:

V - object type

Parameters:

objectStore - object store name, where objects will be inserted

objects - objects to be inserted

callback - called when operation is completed

Throws:

DatabaseException - if no objectStore is associated with object informed

put

<V> void put(V[] objects,
           String objectStore,
           DatabaseCallback callback)

Update all received objects into its associated objectStore. If one object does not exists, create a new one. If no objectStore is associated with object store, a DatabaseException is threw

Type Parameters:

V - object type

Parameters:

objectStore - object store name, where objects will be saved

objects - objects to be saved

callback - called when operation is completed

Throws:

DatabaseException - if no objectStore is associated with object informed

get

<K,V> void get(K key,
             String objectStore,
             DatabaseRetrieveCallback<V> callback)

Retrieve the object associated with the given key from its associated objectStore. If no objectStore is associated with object store, a DatabaseException is threw

Type Parameters:

K - key type

V - object type

Parameters:

key - object key

objectStore - object store name, where objects will be loaded from

callback - called when operation is completed

Throws:

DatabaseException - if no objectStore is associated with object informed

delete

<K> void delete(K key,
              String objectStore,
              DatabaseCallback callback)

Remove the object associated with the given key from its associated objectStore. If no objectStore is associated with object store, a DatabaseException is threw

Type Parameters:

K - key type

Parameters:

key - object key

objectStore - object store name, where objects will be loaded from

callback - called when operation is completed

Throws:

DatabaseException - if no objectStore is associated with object informed

delete

<K> void delete(KeyRange<K> keyRange,
              String objectStore,
              DatabaseCallback callback)

Remove all objects in the given range from its associated objectStore. If no objectStore is associated with object store, a DatabaseException is threw

Type Parameters:

K - key type

Parameters:

keyRange - object key range

objectStore - object store name, where objects will be loaded from

callback - called when operation is completed

Throws:

DatabaseException - if no objectStore is associated with object informed

setDefaultErrorHandler

void setDefaultErrorHandler(DatabaseErrorHandler errorHandler)

Sets an error handler to be called to handle uncaught errors.

Parameters:

errorHandler - the error handler

isSupported

boolean isSupported()

Return true if Crux Database is supported by current browser.

Returns:

true if supported

useWebSQL

void useWebSQL()

Forces Crux to use WEB SQL implementation for its database. This method should be called only for tests purposes. Crux already can detect and choose the better native implementation.

useIndexedDB

void useIndexedDB()

Forces Crux to use Indexed DB implementation for its database. This method should be called only for tests purposes. Crux already can detect and choose the better native implementation.