elemental.html.IDBDatabase Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gwt-elemental Show documentation
There is a newer version: 2.9.0
/*
 * Copyright 2012 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package elemental.html;
import elemental.util.Mappable;
import elemental.util.Indexable;
import elemental.events.EventListener;
import elemental.events.EventTarget;
import elemental.events.Event;

import elemental.events.*;
import elemental.util.*;
import elemental.dom.*;
import elemental.html.*;
import elemental.css.*;
import elemental.stylesheets.*;

import java.util.Date;

/**
  * The IDBDatabase interface of the IndexedDB API provides asynchronous access to a connection to a database. Use it to create, manipulate, and delete objects in that database. The interface also provides the only way to get a transaction and manage versions on that database.
Inherits from: EventTarget
  */
public interface IDBDatabase extends EventTarget {


  /**
    * Name of the connected database.
    */
  String getName();


  /**
    * A list of the names of the object stores currently in the connected database.
    */
  Indexable getObjectStoreNames();

  EventListener getOnabort();

  void setOnabort(EventListener arg);

  EventListener getOnerror();

  void setOnerror(EventListener arg);

  EventListener getOnversionchange();

  void setOnversionchange(EventListener arg);


  /**
    * The version of the connected database. When a database is first created, this attribute is the empty string.
    */
  String getVersion();

  EventRemover addEventListener(String type, EventListener listener);

  EventRemover addEventListener(String type, EventListener listener, boolean useCapture);


  /**
    * Returns immediately and closes the connection in a separate thread. The connection is not actually closed until all transactions created using this connection are complete. No new transactions can be created for this connection once this method is called. Methods that create transactions throw an exception if a closing operation is pending.
void close();

    */
  void close();


  /**
    * Creates and returns a new object store or index. The method takes the name of the store as well as a parameter object. The parameter object lets you define important optional properties. You can use the property to uniquely identify individual objects in the store. As the property is an identifier, it should be unique to every object, and every object should have that property.
But before you can create any object store or index, you must first call the setVersion() method.

Parameters
 name
 The name of the new object store.
 optionalParameters
  Warning: The latest draft of the specification changed this to IDBDatabaseOptionalParameters, which is not yet recognized by any browser
 Optional. Options object whose attributes are optional parameters to the method. It includes the following properties:
    Attribute  Description  
 
   keyPath  The key path to be used by the new object store. If empty or not specified, the object store is created without a key path and uses out-of-line keys.  
  autoIncrement  If true, the object store has a key generator. Defaults to false.  
 
 
 Unknown parameters are ignored.
 

Returns
 IDBObjectStore
 The newly created object store.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The method was not called from a VERSION_CHANGE transaction callback. You must call setVersion() first.  
  CONSTRAINT_ERR  An object store with the given name (based on case-sensitive comparison) already exists in the connected database.  
  NON_TRANSIENT_ERR  optionalParameters has attributes other than keyPath and autoIncrement.  
 


    */
  IDBObjectStore createObjectStore(String name);


  /**
    * Creates and returns a new object store or index. The method takes the name of the store as well as a parameter object. The parameter object lets you define important optional properties. You can use the property to uniquely identify individual objects in the store. As the property is an identifier, it should be unique to every object, and every object should have that property.
But before you can create any object store or index, you must first call the setVersion() method.

Parameters
 name
 The name of the new object store.
 optionalParameters
  Warning: The latest draft of the specification changed this to IDBDatabaseOptionalParameters, which is not yet recognized by any browser
 Optional. Options object whose attributes are optional parameters to the method. It includes the following properties:
    Attribute  Description  
 
   keyPath  The key path to be used by the new object store. If empty or not specified, the object store is created without a key path and uses out-of-line keys.  
  autoIncrement  If true, the object store has a key generator. Defaults to false.  
 
 
 Unknown parameters are ignored.
 

Returns
 IDBObjectStore
 The newly created object store.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The method was not called from a VERSION_CHANGE transaction callback. You must call setVersion() first.  
  CONSTRAINT_ERR  An object store with the given name (based on case-sensitive comparison) already exists in the connected database.  
  NON_TRANSIENT_ERR  optionalParameters has attributes other than keyPath and autoIncrement.  
 


    */
  IDBObjectStore createObjectStore(String name, Mappable options);


  /**
    * Destroys the object store with the given name in the connected database, along with any indexes that reference it. 
As with createObjectStore(), this method can be called only within a VERSION_CHANGE transaction. So you must call the setVersion() method first before you can remove any object store or index.

Parameters
 name
 The name of the data store to delete.

Returns
void
Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The method was not called from a VERSION_CHANGE transaction callback. You must call setVersion() first.  
  NOT_FOUND_ERR  You are trying to delete an object store that does not exist. Names are case sensitive.  
 


    */
  void deleteObjectStore(String name);

  boolean dispatchEvent(Event evt);

  void removeEventListener(String type, EventListener listener);

  void removeEventListener(String type, EventListener listener, boolean useCapture);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(Indexable storeNames);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(Indexable storeNames, String mode);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(String storeName);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(String storeName, String mode);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(Indexable storeNames, int mode);


  /**
    * Immediately returns an IDBTransaction object, and starts a transaction in a separate thread.  The method returns a transaction object (IDBTransaction) containing the objectStore() method, which you can use to access your object store. 

Parameters
 storeNames
 The names of object stores and indexes that are in the scope of the new transaction. Specify only the object stores that you need to access.
 mode
 Optional. The types of access that can be performed in the transaction. Transactions are opened in one of three modes: READ_ONLY, READ_WRITE, and VERSION_CHANGE. If you don't provide the parameter, the default access mode is READ_ONLY. To avoid slowing things down, don't open a READ_WRITE transaction, unless you actually need to write into the database.

Sample code
To start a transaction with the following scope, you can use the code snippets in the table. As noted earlier:
 Add prefixes to the methods in WebKit browsers, (that is, instead of IDBTransaction.READ_ONLY, use webkitIDBTransaction.READ_ONLY).
 The default mode is READ_ONLY, so you don't really have to specify it. Of course, if you need to write into the object store, you can open the transaction in the READ_WRITE mode.

   Scope  Code  
  Single object store   var transaction = db.transaction(['my-store-name'], IDBTransaction.READ_ONLY); 
 Alternatively:
 var transaction = db.transaction('my-store-name', IDBTransaction.READ_ONLY);
  
  Multiple object stores  var transaction = db.transaction(['my-store-name', 'my-store-name2'], IDBTransaction.READ_ONLY);  
  All object stores   var transaction = db.transaction(db.objectStoreNames, IDBTransaction.READ_ONLY);
 You cannot pass an empty array into the storeNames parameter, such as in the following: var transaction = db.transaction([], IDBTransaction.READ_ONLY);.
 Warning:  Accessing all obejct stores under the READ_WRITE mode means that you can run only that transaction. You cannot have writing transactions with overlapping scopes.
  
 
  

Returns
 IDBTransaction
 The transaction object.

Exceptions
This method can raise an IDBDatabaseException with the following codes:
   Exception  Description  
 
   NOT_ALLOWED_ERR  The error is thrown for one of two reasons:  The close() method has been called on this IDBDatabase instance.
 The object store has been deleted or removed.
 
  
  NOT_FOUND_ERR  One of the object stores doesn't exist in the connected database.  
 


    */
  IDBTransaction transaction(String storeName, int mode);
}
Exception	Description
`NOT_ALLOWED_ERR`	The method was not called from a `VERSION_CHANGE` transaction callback. You must call `setVersion()` first.
`CONSTRAINT_ERR`	An object store with the given name (based on case-sensitive comparison) already exists in the connected database.
`NON_TRANSIENT_ERR`	`optionalParameters` has attributes other than `keyPath` and `autoIncrement`.
Exception	Description
`NOT_ALLOWED_ERR`	The method was not called from a `VERSION_CHANGE` transaction callback. You must call `setVersion()` first.
`CONSTRAINT_ERR`	An object store with the given name (based on case-sensitive comparison) already exists in the connected database.
`NON_TRANSIENT_ERR`	`optionalParameters` has attributes other than `keyPath` and `autoIncrement`.
Attribute	Description
`keyPath`	The key path to be used by the new object store. If empty or not specified, the object store is created without a key path and uses out-of-line keys.
`autoIncrement`	If true, the object store has a key generator. Defaults to `false`.
Exception	Description
`NOT_ALLOWED_ERR`	The method was not called from a `VERSION_CHANGE` transaction callback. You must call `setVersion()` first.
`NOT_FOUND_ERR`	You are trying to delete an object store that does not exist. Names are case sensitive.
Exception	Description
`NOT_ALLOWED_ERR`	The error is thrown for one of two reasons: The `close()` method has been called on this IDBDatabase instance. The object store has been deleted or removed.
`NOT_FOUND_ERR`	One of the object stores doesn't exist in the connected database.