You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5469 lines
529 KiB
5469 lines
529 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html dir="ltr" lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<title>Indexed Database API</title>
|
|
|
|
<!--[if IE]>
|
|
<style type='text/css'>
|
|
.ignore {
|
|
-ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=50)";
|
|
filter: alpha(opacity=50);
|
|
}
|
|
</style>
|
|
<![endif]-->
|
|
<style type="text/css">
|
|
table {
|
|
border-collapse: collapse;
|
|
border-style: hidden hidden none;
|
|
}
|
|
table thead {
|
|
border-bottom: medium solid;
|
|
}
|
|
table td, table th {
|
|
border-bottom: thin solid;
|
|
border-left: medium solid;
|
|
border-right: medium solid;
|
|
padding: 0.2em;
|
|
vertical-align: top;
|
|
}
|
|
h5 {
|
|
display: none
|
|
}
|
|
</style>
|
|
|
|
<style type="text/css">
|
|
/*****************************************************************
|
|
* ReSpec CSS
|
|
* Robin Berjon (robin at berjon dot com)
|
|
* v0.05 - 2009-07-31
|
|
*****************************************************************/
|
|
|
|
|
|
/* --- INLINES --- */
|
|
em.rfc2119 {
|
|
text-transform: lowercase;
|
|
font-variant: small-caps;
|
|
font-style: normal;
|
|
color: #900;
|
|
}
|
|
|
|
h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
|
|
h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
|
|
border: none;
|
|
}
|
|
|
|
dfn {
|
|
font-weight: bold;
|
|
}
|
|
|
|
a.internalDFN {
|
|
color: inherit;
|
|
border-bottom: medium solid #99c;
|
|
text-decoration: none;
|
|
}
|
|
|
|
a.externalDFN {
|
|
color: inherit;
|
|
border-bottom: medium dotted #ccc;
|
|
text-decoration: none;
|
|
}
|
|
|
|
a.bibref {
|
|
text-decoration: none;
|
|
}
|
|
|
|
code {
|
|
color: #ff4500;
|
|
}
|
|
|
|
|
|
/* --- WEB IDL --- */
|
|
pre.idl {
|
|
border-top: 1px solid #90b8de;
|
|
border-bottom: 1px solid #90b8de;
|
|
padding: 1em;
|
|
line-height: 120%;
|
|
}
|
|
|
|
pre.idl::before {
|
|
content: "WebIDL";
|
|
display: block;
|
|
width: 150px;
|
|
background: #90b8de;
|
|
color: #fff;
|
|
font-family: initial;
|
|
padding: 3px;
|
|
font-weight: bold;
|
|
margin: -1em 0 1em -1em;
|
|
}
|
|
|
|
.idlType {
|
|
color: #ff4500;
|
|
font-weight: bold;
|
|
text-decoration: none;
|
|
}
|
|
|
|
/*.idlModule*/
|
|
/*.idlModuleID*/
|
|
/*.idlInterface*/
|
|
.idlInterfaceID {
|
|
font-weight: bold;
|
|
color: #005a9c;
|
|
}
|
|
|
|
.idlSuperclass {
|
|
font-style: italic;
|
|
color: #005a9c;
|
|
}
|
|
|
|
/*.idlAttribute*/
|
|
.idlAttrType, .idlFieldType {
|
|
color: #005a9c;
|
|
}
|
|
.idlAttrName, .idlFieldName {
|
|
color: #ff4500;
|
|
}
|
|
.idlAttrName a, .idlFieldName a {
|
|
color: #ff4500;
|
|
border-bottom: 1px dotted #ff4500;
|
|
text-decoration: none;
|
|
}
|
|
|
|
/*.idlMethod*/
|
|
.idlMethType {
|
|
color: #005a9c;
|
|
}
|
|
.idlMethName {
|
|
color: #ff4500;
|
|
}
|
|
.idlMethName a {
|
|
color: #ff4500;
|
|
border-bottom: 1px dotted #ff4500;
|
|
text-decoration: none;
|
|
}
|
|
|
|
/*.idlParam*/
|
|
.idlParamType {
|
|
color: #005a9c;
|
|
}
|
|
.idlParamName {
|
|
font-style: italic;
|
|
}
|
|
|
|
.extAttr {
|
|
color: #666;
|
|
}
|
|
|
|
/*.idlConst*/
|
|
.idlConstType {
|
|
color: #005a9c;
|
|
}
|
|
.idlConstName {
|
|
color: #ff4500;
|
|
}
|
|
.idlConstName a {
|
|
color: #ff4500;
|
|
border-bottom: 1px dotted #ff4500;
|
|
text-decoration: none;
|
|
}
|
|
|
|
/*.idlException*/
|
|
.idlExceptionID {
|
|
font-weight: bold;
|
|
color: #c00;
|
|
}
|
|
|
|
.idlTypedefID, .idlTypedefType {
|
|
color: #005a9c;
|
|
}
|
|
|
|
.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
|
|
color: #c00;
|
|
font-weight: normal;
|
|
}
|
|
|
|
.excName a {
|
|
font-family: monospace;
|
|
}
|
|
|
|
.idlRaises a.idlType, .excName a.idlType {
|
|
border-bottom: 1px dotted #c00;
|
|
}
|
|
|
|
.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
|
|
width: 45px;
|
|
text-align: center;
|
|
}
|
|
.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
|
|
.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
|
|
|
|
.idlImplements a {
|
|
font-weight: bold;
|
|
}
|
|
|
|
dl.attributes, dl.methods, dl.constants, dl.fields {
|
|
margin-left: 2em;
|
|
}
|
|
|
|
.attributes dt, .methods dt, .constants dt, .fields dt {
|
|
font-weight: normal;
|
|
}
|
|
|
|
.attributes dt code, .methods dt code, .constants dt code, .fields dt code {
|
|
font-weight: bold;
|
|
color: #000;
|
|
font-family: monospace;
|
|
}
|
|
|
|
.attributes dt code, .fields dt code {
|
|
background: #ffffd2;
|
|
}
|
|
|
|
.attributes dt .idlAttrType code, .fields dt .idlFieldType code {
|
|
color: #005a9c;
|
|
background: transparent;
|
|
font-family: inherit;
|
|
font-weight: normal;
|
|
font-style: italic;
|
|
}
|
|
|
|
.methods dt code {
|
|
background: #d9e6f8;
|
|
}
|
|
|
|
.constants dt code {
|
|
background: #ddffd2;
|
|
}
|
|
|
|
.attributes dd, .methods dd, .constants dd, .fields dd {
|
|
margin-bottom: 1em;
|
|
}
|
|
|
|
table.parameters, table.exceptions {
|
|
border-spacing: 0;
|
|
border-collapse: collapse;
|
|
margin: 0.5em 0;
|
|
width: 100%;
|
|
}
|
|
table.parameters { border-bottom: 1px solid #90b8de; }
|
|
table.exceptions { border-bottom: 1px solid #deb890; }
|
|
|
|
.parameters th, .exceptions th {
|
|
color: #fff;
|
|
padding: 3px 5px;
|
|
text-align: left;
|
|
font-family: initial;
|
|
font-weight: normal;
|
|
text-shadow: #666 1px 1px 0;
|
|
}
|
|
.parameters th { background: #90b8de; }
|
|
.exceptions th { background: #deb890; }
|
|
|
|
.parameters td, .exceptions td {
|
|
padding: 3px 10px;
|
|
border-top: 1px solid #ddd;
|
|
vertical-align: top;
|
|
}
|
|
|
|
.parameters tr:first-child td, .exceptions tr:first-child td {
|
|
border-top: none;
|
|
}
|
|
|
|
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
|
|
width: 100px;
|
|
}
|
|
|
|
.parameters td.prmType {
|
|
width: 120px;
|
|
}
|
|
|
|
table.exceptions table {
|
|
border-spacing: 0;
|
|
border-collapse: collapse;
|
|
width: 100%;
|
|
}
|
|
|
|
/* --- TOC --- */
|
|
.toc a {
|
|
text-decoration: none;
|
|
}
|
|
|
|
a .secno {
|
|
color: #000;
|
|
}
|
|
|
|
/* --- TABLE --- */
|
|
table.simple {
|
|
border-spacing: 0;
|
|
border-collapse: collapse;
|
|
border-bottom: 3px solid #005a9c;
|
|
}
|
|
|
|
.simple th {
|
|
background: #005a9c;
|
|
color: #fff;
|
|
padding: 3px 5px;
|
|
text-align: left;
|
|
}
|
|
|
|
.simple th[scope=row] {
|
|
background: inherit;
|
|
color: inherit;
|
|
border-top: 1px solid #ddd;
|
|
}
|
|
|
|
.simple td {
|
|
padding: 3px 10px;
|
|
border-top: 1px solid #ddd;
|
|
}
|
|
|
|
.simple tr:nth-child(even) {
|
|
background: #f0f6ff;
|
|
}
|
|
|
|
/* --- DL --- */
|
|
.section dd > p:first-child {
|
|
margin-top: 0;
|
|
}
|
|
|
|
.section dd > p:last-child {
|
|
margin-bottom: 0;
|
|
}
|
|
|
|
.section dd {
|
|
margin-bottom: 1em;
|
|
}
|
|
|
|
.section dl.attrs dd, .section dl.eldef dd {
|
|
margin-bottom: 0;
|
|
}
|
|
|
|
/* --- EXAMPLES --- */
|
|
pre.example {
|
|
border-top: 1px solid #ff4500;
|
|
border-bottom: 1px solid #ff4500;
|
|
padding: 1em;
|
|
margin-top: 1em;
|
|
}
|
|
|
|
pre.example::before {
|
|
content: "Example";
|
|
display: block;
|
|
width: 150px;
|
|
background: #ff4500;
|
|
color: #fff;
|
|
font-family: initial;
|
|
padding: 3px;
|
|
font-weight: bold;
|
|
margin: -1em 0 1em -1em;
|
|
}
|
|
|
|
/* --- EDITORIAL NOTES --- */
|
|
.issue {
|
|
padding: 1em;
|
|
border: 1px solid #f00;
|
|
background: #ffc;
|
|
}
|
|
|
|
.issue::before {
|
|
content: "Issue";
|
|
display: block;
|
|
width: 150px;
|
|
margin: -1.5em 0 0.5em 0;
|
|
font-weight: bold;
|
|
border: 1px solid #f00;
|
|
background: #fff;
|
|
padding: 3px 1em;
|
|
}
|
|
|
|
.note {
|
|
padding: 1em;
|
|
border: 2px solid #cff6d9;
|
|
background: #e2fff0;
|
|
}
|
|
|
|
.note::before {
|
|
content: "Note";
|
|
display: block;
|
|
width: 150px;
|
|
margin: -1.5em 0 0.5em 0;
|
|
font-weight: bold;
|
|
border: 1px solid #cff6d9;
|
|
background: #fff;
|
|
padding: 3px 1em;
|
|
}
|
|
|
|
/* --- SYNTAX HIGHLIGHTING --- */
|
|
pre.sh_sourceCode {
|
|
background-color: white;
|
|
color: black;
|
|
font-style: normal;
|
|
font-weight: normal;
|
|
}
|
|
|
|
pre.sh_sourceCode .sh_keyword { color: #005a9c; font-weight: bold; } /* language keywords */
|
|
pre.sh_sourceCode .sh_type { color: #666; } /* basic types */
|
|
pre.sh_sourceCode .sh_usertype { color: teal; } /* user defined types */
|
|
pre.sh_sourceCode .sh_string { color: red; font-family: monospace; } /* strings and chars */
|
|
pre.sh_sourceCode .sh_regexp { color: orange; font-family: monospace; } /* regular expressions */
|
|
pre.sh_sourceCode .sh_specialchar { color: #ffc0cb; font-family: monospace; } /* e.g., \n, \t, \\ */
|
|
pre.sh_sourceCode .sh_comment { color: #A52A2A; font-style: italic; } /* comments */
|
|
pre.sh_sourceCode .sh_number { color: purple; } /* literal numbers */
|
|
pre.sh_sourceCode .sh_preproc { color: #00008B; font-weight: bold; } /* e.g., #include, import */
|
|
pre.sh_sourceCode .sh_symbol { color: blue; } /* e.g., *, + */
|
|
pre.sh_sourceCode .sh_function { color: black; font-weight: bold; } /* function calls and declarations */
|
|
pre.sh_sourceCode .sh_cbracket { color: red; } /* block brackets (e.g., {, }) */
|
|
pre.sh_sourceCode .sh_todo { font-weight: bold; background-color: #00FFFF; } /* TODO and FIXME */
|
|
|
|
/* Predefined variables and functions (for instance glsl) */
|
|
pre.sh_sourceCode .sh_predef_var { color: #00008B; }
|
|
pre.sh_sourceCode .sh_predef_func { color: #00008B; font-weight: bold; }
|
|
|
|
/* for OOP */
|
|
pre.sh_sourceCode .sh_classname { color: teal; }
|
|
|
|
/* line numbers (not yet implemented) */
|
|
pre.sh_sourceCode .sh_linenum { display: none; }
|
|
|
|
/* Internet related */
|
|
pre.sh_sourceCode .sh_url { color: blue; text-decoration: underline; font-family: monospace; }
|
|
|
|
/* for ChangeLog and Log files */
|
|
pre.sh_sourceCode .sh_date { color: blue; font-weight: bold; }
|
|
pre.sh_sourceCode .sh_time, pre.sh_sourceCode .sh_file { color: #00008B; font-weight: bold; }
|
|
pre.sh_sourceCode .sh_ip, pre.sh_sourceCode .sh_name { color: #006400; }
|
|
|
|
/* for Prolog, Perl... */
|
|
pre.sh_sourceCode .sh_variable { color: #006400; }
|
|
|
|
/* for LaTeX */
|
|
pre.sh_sourceCode .sh_italics { color: #006400; font-style: italic; }
|
|
pre.sh_sourceCode .sh_bold { color: #006400; font-weight: bold; }
|
|
pre.sh_sourceCode .sh_underline { color: #006400; text-decoration: underline; }
|
|
pre.sh_sourceCode .sh_fixed { color: green; font-family: monospace; }
|
|
pre.sh_sourceCode .sh_argument { color: #006400; }
|
|
pre.sh_sourceCode .sh_optionalargument { color: purple; }
|
|
pre.sh_sourceCode .sh_math { color: orange; }
|
|
pre.sh_sourceCode .sh_bibtex { color: blue; }
|
|
|
|
/* for diffs */
|
|
pre.sh_sourceCode .sh_oldfile { color: orange; }
|
|
pre.sh_sourceCode .sh_newfile { color: #006400; }
|
|
pre.sh_sourceCode .sh_difflines { color: blue; }
|
|
|
|
/* for css */
|
|
pre.sh_sourceCode .sh_selector { color: purple; }
|
|
pre.sh_sourceCode .sh_property { color: blue; }
|
|
pre.sh_sourceCode .sh_value { color: #006400; font-style: italic; }
|
|
|
|
/* other */
|
|
pre.sh_sourceCode .sh_section { color: black; font-weight: bold; }
|
|
pre.sh_sourceCode .sh_paren { color: red; }
|
|
pre.sh_sourceCode .sh_attribute { color: #006400; }
|
|
|
|
</style><style type="text/css">.nt, pre, .terminal, code, .prop, .esstring, .javavalue, .idlident, .idlstring, .xattr, .regex, .prod-number, .prod-lines, .prod-mid {
|
|
font-size: 14px;
|
|
}
|
|
pre code, .prod-lines .nt {
|
|
font-size: 14px !important;
|
|
}
|
|
.ednote, .terminal, code, .prop, .esstring, .javavalue, .idlident, .idlstring, .example, /*.note,*/ blockquote {
|
|
background: #d9e8ff;
|
|
}
|
|
td code {
|
|
background: inherit;
|
|
}
|
|
.example blockquote {
|
|
background: #f0f6ff;
|
|
}
|
|
table.grammar {
|
|
background: #eee;
|
|
}
|
|
.ednote {
|
|
border-top: 3px solid red;
|
|
border-bottom: 3px solid red;
|
|
margin: 1em 2em;
|
|
padding: 0 1em 0 1em;
|
|
background: #f8eeee;
|
|
}
|
|
.ednoteHeader {
|
|
font-weight: bold;
|
|
display: block;
|
|
padding-top: 0.5em;
|
|
}
|
|
ul.toc li {
|
|
list-style-type: none;
|
|
margin-top: 0;
|
|
margin-bottom: 0;
|
|
}
|
|
ul.toc {
|
|
margin-bottom: 0.5em;
|
|
}
|
|
.terminal, code, .prop, .esstring, .javavalue, .idlident, .idlstring, .input {
|
|
font-family: /*Consolas, Monaco,*/ monospace !important;
|
|
}
|
|
pre.code code {
|
|
background: inherit;
|
|
}
|
|
.propattrset {
|
|
}
|
|
/*.prop {
|
|
font-family: Consolas, Monaco, monospace;
|
|
}*/
|
|
table.vert {
|
|
border-collapse: collapse;
|
|
border-top: 2px solid #005a9c;
|
|
border-bottom: 2px solid #005a9c;
|
|
margin-top: 1em;
|
|
margin-bottom: 1em;
|
|
margin-left: auto;
|
|
margin-right: auto;
|
|
}
|
|
table.vert td {
|
|
background: #f0f6ff;
|
|
}
|
|
table.vert th {
|
|
text-align: left;
|
|
vertical-align: bottom;
|
|
background: #d9e8ff;
|
|
color: #005a9c;
|
|
color: black;
|
|
border-bottom: 2px solid #005a9c;
|
|
white-space: nowrap;
|
|
}
|
|
table.vert td {
|
|
/*border-top: 1px solid #a2c4e6;
|
|
border-bottom: 1px solid #a2c4e6;*/
|
|
vertical-align: top;
|
|
}
|
|
table.vert th, table.vert td {
|
|
padding: 0.25em 0.75em;
|
|
}
|
|
table.vert td.table-note {
|
|
background: none;
|
|
border-left: 1px solid white;
|
|
border-right: 1px solid white;
|
|
border-bottom: 1px solid white;
|
|
font-size: 90%;
|
|
}
|
|
.xattr {
|
|
font-family: /*Consolas, Monaco,*/ monospace;
|
|
}
|
|
table.grammar {
|
|
border-collapse: collapse;
|
|
padding: 0.5em;
|
|
margin: 0 2em;
|
|
overflow: auto;
|
|
}
|
|
table.grammar td {
|
|
vertical-align: top;
|
|
margin: 0;
|
|
padding: 0.325em 1em;
|
|
font-family: /*Consolas, Monaco,*/ monospace;
|
|
}
|
|
table.grammar td.prod-rhs {
|
|
vertical-align: inherit;
|
|
}
|
|
.nt, .prod-lines {
|
|
font-family: /*Consolas, Monaco,*/ monospace;
|
|
white-space: nowrap;
|
|
}
|
|
.idltype, .idlvalue {
|
|
font-weight: bold;
|
|
}
|
|
.idlop {
|
|
font-weight: bold;
|
|
}
|
|
.esvalue, .estype {
|
|
font-weight: bold;
|
|
}
|
|
.javatype, .javapkg {
|
|
font-weight: bold;
|
|
}
|
|
.regex {
|
|
font-family: /*Consolas, Monaco,*/ monospace;
|
|
white-space: nowrap;
|
|
}
|
|
.typevar {
|
|
font-style: italic;
|
|
}
|
|
.example/*, .note*/ {
|
|
border-top: 3px solid #005a9c;
|
|
border-bottom: 3px solid #005a9c;
|
|
margin: 1em 2em;
|
|
padding: 0 1em 0 1em;
|
|
}
|
|
.exampleHeader, .noteHeader {
|
|
font-weight: bold;
|
|
display: block;
|
|
color: #005a9c;
|
|
color: black;
|
|
padding-top: 0.5em;
|
|
}
|
|
pre {
|
|
overflow: auto;
|
|
margin: 0;
|
|
font-family: /*Consolas, Monaco,*/ monospace;
|
|
}
|
|
pre.code {
|
|
padding: 0 1em;
|
|
margin: 0;
|
|
margin-bottom: 1em;
|
|
}
|
|
.block {
|
|
border: 1px solid #90b8de;
|
|
border-left: 3px double #90b8de;
|
|
border-left: none;
|
|
border-right: none;
|
|
background: #f0f6ff;
|
|
margin: 2em;
|
|
margin-top: 1em;
|
|
margin-bottom: 1em;
|
|
padding: 0 0.5em;
|
|
padding-bottom: 0.5em;
|
|
}
|
|
.blockTitleDiv {
|
|
text-align: left;
|
|
}
|
|
.blockTitle {
|
|
position: relative;
|
|
top: -0.75em;
|
|
left: -1.5em;
|
|
/*border: 1px solid #90b8de;
|
|
border-left: none;
|
|
border-right: none;*/
|
|
background: #90b8de;
|
|
color: white;
|
|
padding: 0.25em 1em 0.25em 1em;
|
|
font-weight: bold;
|
|
font-size: 80%;
|
|
}
|
|
dfn {
|
|
font-weight: bold;
|
|
font-style: italic;
|
|
}
|
|
.dfnref {
|
|
}
|
|
li {
|
|
margin-top: 0.5em;
|
|
margin-bottom: 0.5em;
|
|
}
|
|
ul > li {
|
|
list-style-type: disc;
|
|
}
|
|
.norm {
|
|
font-style: italic;
|
|
}
|
|
.rfc2119 {
|
|
text-transform: lowercase;
|
|
font-variant: small-caps;
|
|
}
|
|
dfn var {
|
|
font-style: normal;
|
|
}
|
|
blockquote {
|
|
padding: 1px 1em;
|
|
margin-left: 2em;
|
|
margin-right: 2em;
|
|
}
|
|
a.placeholder {
|
|
color: #00e;
|
|
}
|
|
dl.changes > dd {
|
|
margin-left: 0;
|
|
}
|
|
dd > :first-child {
|
|
margin-top: 0;
|
|
}
|
|
caption {
|
|
caption-side: bottom;
|
|
margin-top: 1em;
|
|
font-weight: bold;
|
|
}
|
|
body {
|
|
line-height: 1.3;
|
|
}
|
|
@media print {
|
|
.section-link {
|
|
display: none;
|
|
}
|
|
}
|
|
.section-link {
|
|
visibility: hidden;
|
|
width: 1px;
|
|
height: 1px;
|
|
overflow: visible;
|
|
font-size: 10pt;
|
|
font-style: normal;
|
|
}
|
|
.section-link a {
|
|
color: #666;
|
|
font-weight: bold;
|
|
text-decoration: none;
|
|
}
|
|
.section-link a:hover {
|
|
color: #c00;
|
|
}
|
|
.section > *:hover > .section-link {
|
|
visibility: visible;
|
|
}
|
|
div.set {
|
|
margin-left: 3em;
|
|
text-indent: -1em;
|
|
}
|
|
ol.algorithm ol {
|
|
border-left: 1px solid #90b8de;
|
|
margin-left: 1em;
|
|
}
|
|
dl.switch > dd > ol.only {
|
|
margin-left: 0;
|
|
}
|
|
dl.switch {
|
|
padding-left: 2em;
|
|
}
|
|
dl.switch > dt {
|
|
text-indent: -1.5em;
|
|
margin-top: 1em;
|
|
}
|
|
dl.switch > dt + dt {
|
|
margin-top: 0;
|
|
}
|
|
dl.switch > dt:before {
|
|
content: '\21AA';
|
|
padding: 0 0.5em 0 0;
|
|
display: inline-block;
|
|
width: 1em;
|
|
text-align: right;
|
|
line-height: 0.5em;
|
|
}
|
|
.diagram {
|
|
text-align: center;
|
|
}
|
|
iframe {
|
|
border: 0;
|
|
}
|
|
.comment {
|
|
color: #005a9c;
|
|
}
|
|
.matrix {
|
|
border-collapse: collapse;
|
|
margin-left: auto;
|
|
margin-right: auto;
|
|
}
|
|
.matrix th {
|
|
background: #d9e8ff;
|
|
text-align: right;
|
|
}
|
|
.matrix td, .matrix th {
|
|
border: 1px solid #90b8de;
|
|
padding: 4px;
|
|
}
|
|
.matrix th.corner {
|
|
border: 0;
|
|
background: none;
|
|
}
|
|
.matrix td {
|
|
text-align: center;
|
|
background: #f0f6ff;
|
|
}
|
|
.matrix .belowdiagonal {
|
|
background: #ddd;
|
|
}
|
|
|
|
ul.notes { font-size: 90%; padding-left: 0 }
|
|
ul.notes li { list-style-type: none }
|
|
ul.notes .note-link { vertical-align: super }
|
|
.note-link { font-size: 90% }
|
|
|
|
.code var { color: #f44; }
|
|
|
|
/* For dfn.js */
|
|
body.dfnEnabled dfn { cursor: pointer; }
|
|
.dfnPanel {
|
|
display: inline;
|
|
position: absolute;
|
|
height: auto;
|
|
width: auto;
|
|
padding: 0.5em 0.75em;
|
|
font: small sans-serif;
|
|
background: #DDDDDD;
|
|
color: black;
|
|
border: outset 0.2em;
|
|
cursor: default;
|
|
}
|
|
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
|
|
.dfnPanel :link, .dfnPanel :visited { color: black; }
|
|
.dfnPanel p { font-weight: bolder; }
|
|
.dfnPanel li { list-style-position: inside; }
|
|
</style>
|
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-WD.css">
|
|
</head>
|
|
|
|
<body style="display: inherit;">
|
|
<div class="head">
|
|
<p>
|
|
<a href="http://www.w3.org/"><img height="48" width="72" alt="W3C" src="http://www.w3.org/Icons/w3c_home"></a>
|
|
</p>
|
|
|
|
<h1 class="title" id="title">Indexed Database API</h1>
|
|
<h2 id="w3c-working-draft-06-december-2011"><acronym title="World Wide Web Consortium">W3C</acronym> Working Draft 06 December 2011</h2>
|
|
<dl>
|
|
<dt>This version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2011/WD-IndexedDB-20111206/">http://www.w3.org/TR/2011/WD-IndexedDB-20111206/</a></dd>
|
|
|
|
<dt>Latest published version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/IndexedDB/">http://www.w3.org/TR/IndexedDB/</a></dd>
|
|
|
|
<dt>Latest editor's draft:</dt>
|
|
<dd><a href="http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html">http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html</a></dd>
|
|
|
|
<dt>Previous version:</dt>
|
|
<dd><a href="http://www.w3.org/TR/2011/WD-IndexedDB-20110419/">http://www.w3.org/TR/2011/WD-IndexedDB-20110419/</a></dd>
|
|
|
|
<dt>Editors:</dt>
|
|
<dd><a href="mailto:nikunj@o-micron.com">Nikunj Mehta</a>, Invited Expert</dd>
|
|
<dd><a href="mailto:jonas@sicking.cc">Jonas Sicking</a>, Mozilla</dd>
|
|
<dd><a href="mailto:eliotgra@microsoft.com">Eliot Graff</a>, Microsoft</dd>
|
|
<dd><a href="mailto:andreip@google.com">Andrei Popescu</a>, Google</dd>
|
|
<dd><a href="mailto:jorlow@google.com">Jeremy Orlow</a>, Google</dd>
|
|
</dl>
|
|
<p class="copyright">
|
|
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2011
|
|
<a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup>
|
|
(<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>,
|
|
<a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>,
|
|
<a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
|
|
W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
|
|
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and
|
|
<a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.
|
|
</p>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="introductory section" id="abstract"><h2>Abstract</h2>
|
|
<p>
|
|
This document defines APIs for a database of records holding simple values
|
|
and hierarchical objects. Each record consists of a key and some value.
|
|
Moreover, the database maintains indexes over records it stores. An
|
|
application developer directly uses an API to locate records either by
|
|
their key or by using an index. A query language can be layered on this
|
|
API. An indexed database can be implemented using a persistent B-tree data
|
|
structure.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="sotd" class="introductory section">
|
|
<h2>Status of This Document</h2>
|
|
<p>
|
|
<em>This section describes the status of this document at the time of its publication.
|
|
Other documents may supersede this document.
|
|
A list of current W3C publications and the latest revision of this technical report can be found in the
|
|
<a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em>
|
|
</p>
|
|
<p>
|
|
This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a> as a Working Draft.
|
|
If you wish to make comments regarding this document, please send them to
|
|
<a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a>
|
|
(<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>,
|
|
<a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>).
|
|
All feedback is welcome.
|
|
</p>
|
|
<p>
|
|
Publication as a Working Draft does not imply endorsement by the W3C Membership.
|
|
This is a draft document and may be updated, replaced or obsoleted by other documents at any time.
|
|
It is inappropriate to cite this document as other than work in progress.
|
|
</p>
|
|
<p>
|
|
This document was produced by a group operating under the
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>.
|
|
W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a>
|
|
made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent.
|
|
An individual who has actual knowledge of a patent which the individual believes contains
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information
|
|
in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.
|
|
</p>
|
|
</div>
|
|
<div class="section" id="toc">
|
|
<h2 class="introductory">Table of Contents</h2>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#introduction"><span class="secno">1. </span>Introduction</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#conformance"><span class="secno">2. </span>Conformance</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#dependencies"><span class="secno">2.1 </span>Dependencies</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#database-api"><span class="secno">3. </span>Indexed Database API</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#constructs"><span class="secno">3.1 </span>Constructs</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#database-concept"><span class="secno">3.1.1 </span>Database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store-concept"><span class="secno">3.1.2 </span>Object Store</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#key-construct"><span class="secno">3.1.3 </span>Keys</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#value-construct"><span class="secno">3.1.4 </span>Values</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#key-path-construct"><span class="secno">3.1.5 </span>Key Path</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#index-concept"><span class="secno">3.1.6 </span>Index</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#transaction-concept"><span class="secno">3.1.7 </span>Transaction</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#request-concept"><span class="secno">3.1.8 </span>Requests</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#range-concept"><span class="secno">3.1.9 </span>Key Range</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cursor-concept"><span class="secno">3.1.10 </span>Cursor</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#exceptions"><span class="secno">3.1.11 </span>Exceptions</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#options-object-concept"><span class="secno">3.1.12 </span>Options Object</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#async-api"><span class="secno">3.2 </span>Asynchronous APIs</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#request-api"><span class="secno">3.2.1 </span>The <code>IDBRequest</code> Interface</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#events"><span class="secno">3.2.2 </span>Event interfaces</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#requests"><span class="secno">3.2.3 </span>Opening a database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#database-interface"><span class="secno">3.2.4 </span>Database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store"><span class="secno">3.2.5 </span>Object Store</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#index"><span class="secno">3.2.6 </span>Index</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cursor"><span class="secno">3.2.7 </span>Cursor</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#transaction"><span class="secno">3.2.8 </span>Transaction</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#sync-database"><span class="secno">3.3 </span>Synchronous APIs</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#opening-sync"><span class="secno">3.3.1 </span>Opening a database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#database-interface-sync"><span class="secno">3.3.2 </span>Database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store-sync"><span class="secno">3.3.3 </span>Object Store</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#index-sync"><span class="secno">3.3.4 </span>Index</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cursor-sync"><span class="secno">3.3.5 </span>Cursor</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#transaction-sync"><span class="secno">3.3.6 </span>Transaction</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#algorithms"><span class="secno">4. </span>Algorithms</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#opening"><span class="secno">4.1 </span>Opening a database</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#transaction-creation-steps"><span class="secno">4.2 </span>Transaction Creation steps</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#steps-for-committing-a-transaction"><span class="secno">4.3 </span>Steps for committing a transaction</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#steps-for-aborting-a-transaction"><span class="secno">4.4 </span>Steps for aborting a transaction</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#steps-for-asynchronously-executing-a-request"><span class="secno">4.5 </span>Steps for asynchronously executing a <span class="internalDFN formerLink internalDFN">request</span></a></li>
|
|
<li class="tocline"><a class="tocxref" href="#steps-for-synchronously-executing-a-request"><span class="secno">4.6 </span>Steps for synchronously executing a <span class="internalDFN formerLink internalDFN">request</span></a></li>
|
|
<li class="tocline"><a class="tocxref" href="#steps-for-extracting-a-key-from-a-value-using-a-key-path"><span class="secno">4.7 </span>Steps for extracting a key from a value using a <span class="internalDFN formerLink internalDFN">key path</span></a></li>
|
|
<li class="tocline"><a class="tocxref" href="#version_change-transaction-steps"><span class="secno">4.8 </span>VERSION_CHANGE transaction steps</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#database-closing-steps"><span class="secno">4.9 </span>Database closing steps</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#database-deletion-steps"><span class="secno">4.10 </span>Database deletion steps</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#fire-a-success-event"><span class="secno">4.11 </span>Fire a success event</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#fire-an-error-event"><span class="secno">4.12 </span>Fire an error event</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#database-operations"><span class="secno">5. </span>Database operations</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#object-store-storage-operation"><span class="secno">5.1 </span>Object Store Storage Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store-retrieval-operation"><span class="secno">5.2 </span>Object Store Retrieval Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#index-referenced-value-retrieval-operation"><span class="secno">5.3 </span>Index Referenced Value Retrieval Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#index-value-retrieval-operation"><span class="secno">5.4 </span>Index Value Retrieval Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store-deletion-operation"><span class="secno">5.5 </span>Object Store Deletion Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#object-store-clear-operation"><span class="secno">5.6 </span>Object Store Clear Operation</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cursor-iteration-operation"><span class="secno">5.7 </span>Cursor Iteration Operation</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#privacy"><span class="secno">6. </span>Privacy</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#user-tracking"><span class="secno">6.1 </span>User tracking</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cookie-resurrection"><span class="secno">6.2 </span>Cookie resurrection</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#sensitivity-of-data"><span class="secno">6.3 </span>Sensitivity of data</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#authorization"><span class="secno">7. </span>Authorization</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#dns-spoofing-attacks"><span class="secno">7.1 </span>DNS spoofing attacks</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#cross-directory-attacks"><span class="secno">7.2 </span>Cross-directory attacks</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#implementation-risks"><span class="secno">7.3 </span>Implementation risks</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="tocline"><a class="tocxref" href="#requirements"><span class="secno">A. </span>Requirements</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#acknowledgements"><span class="secno">B. </span>Acknowledgements</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#references"><span class="secno">C. </span>References</a>
|
|
<ul class="toc">
|
|
<li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">C.1 </span>Normative references</a></li>
|
|
<li class="tocline"><a class="tocxref" href="#informative-references"><span class="secno">C.2 </span>Informative references</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="introduction" class="section informative">
|
|
<!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
|
|
|
|
|
|
<p>
|
|
User agents need to store large numbers of objects locally in
|
|
order to satisfy off-line data requirements of Web applications.
|
|
[<cite><a href="#bib-WEBSTORAGE" rel="biblioentry" class="bibref">WEBSTORAGE</a></cite>] is useful for
|
|
storing pairs of keys and their corresponding values. However, it does
|
|
not provide in-order retrieval of keys, efficient searching over
|
|
values, or storage of duplicate values for a key.
|
|
</p>
|
|
|
|
<p>
|
|
This specification provides a concrete API to perform advanced key-value data management
|
|
that is at the heart of most sophisticated query processors. It does
|
|
so by using transactional databases to store keys and their
|
|
corresponding values (one or more per key), and providing a means
|
|
of traversing keys in a deterministic order. This is often implemented
|
|
through the use of persistent B-tree data structures that are considered
|
|
efficient for insertion and deletion as well as in-order traversal of
|
|
very large numbers of data records.
|
|
</p>
|
|
|
|
<p class="issue">
|
|
TODO: Add examples using the sync and the async APIs.
|
|
</p>
|
|
|
|
<!-- We need and example, but until this one is updated, it's doing more harm than good.
|
|
<div class="example">
|
|
<p>
|
|
A script can efficiently find records in an object store that come
|
|
closest to the required value provided the value is stored in either
|
|
a primary or a secondary key.
|
|
In the following example, the 'books' object store holds data about
|
|
books which are stored by their 'isbn' attribute. Additionally,
|
|
an index is maintained on the 'author' attribute of the objects
|
|
stored in the object store. This index can be used to look up books
|
|
for a given author. If an exact match is not found, the operation
|
|
raises an exception.
|
|
</p>
|
|
<codeblock>var db = indexedDB.open('books', 'Book store', false);
|
|
if (db.version !== '1.0') {
|
|
var olddb = indexedDB.open('books', 'Book store');
|
|
olddb.createObjectStore('books', 'isbn');
|
|
olddb.createIndex('BookAuthor', 'books', 'author', false);
|
|
olddb.setVersion("1.0");
|
|
}
|
|
// db.version === "1.0";
|
|
var index = db.openIndex('BookAuthor');
|
|
var matching = index.get('fred');
|
|
if (matching)
|
|
report(matching.isbn, matching.name, matching.author);
|
|
else
|
|
report(null);</codeblock>
|
|
<p>
|
|
The next example performs the exact same logic as above asynchronously.
|
|
</p>
|
|
<codeblock>
|
|
function findFred() {
|
|
var store = db.objectStore('books');
|
|
var index = store.index('BookAuthor');
|
|
var req = index.get('fred');
|
|
req.onsuccess = function(event) {
|
|
var matching = event.result;
|
|
report(matching.isbn, matching.name, matching.author);
|
|
}
|
|
req.onerror = function(event) {
|
|
report(null);
|
|
}
|
|
}
|
|
|
|
var db;
|
|
var dbRequest = indexedDB.open('books', 'Book store');
|
|
dbRequest.onsuccess = function(event) {
|
|
db = event.result;
|
|
if (db.version != "1.0") {
|
|
var versionRequest = db.setVersion("1.0");
|
|
versionRequest.ontimeout = function(event) {
|
|
throw new Error("timeout trying to set version to 1.0");
|
|
}
|
|
versionRequest.onsuccess = function(event) {
|
|
var store = db.createObjectStore('books', 'isbn');
|
|
store.createIndex('BookAuthor', 'books', 'author', false);
|
|
event.transaction.onabort = function(event) {
|
|
throw new Error("error while trying to set version to 1.0");
|
|
}
|
|
event.transaction.oncomplete = function(event) {
|
|
findFred(db);
|
|
}
|
|
}
|
|
} else {
|
|
findFred(db);
|
|
}
|
|
}
|
|
|
|
</codeblock>
|
|
<p>
|
|
Here is an example of a script using this API. First, a function
|
|
<code>prepareDatabase()</code> is defined. This function tries to create
|
|
the database if necessary, giving it one object store called "docids" with
|
|
the primary key "id". If it is successful, or if the table
|
|
doesn't need creating, it calls the function that does the
|
|
actual work, in this case <code>showDocCount()</code>.
|
|
</p>
|
|
<codeblock>
|
|
var request = null;
|
|
function prepareDatabase(ready, error) {
|
|
request = new <a>IDBDatabaseRequest</a>();
|
|
request.<a>onsuccess</a> = ready;
|
|
request.<a>onerror</a> = error;
|
|
var upgrade =
|
|
function(changes, db) {
|
|
changes.<a>createObjectStore</a>('docids', 'id');
|
|
// now db.<a>version</a> === '1.0'
|
|
};
|
|
request.<a>open</a>('documents', '1.0', 'Offline document storage', upgrade);
|
|
}
|
|
|
|
function showDocCount(db, span) {
|
|
var storeRequest = new <a>IDBObjectStoreRequest</a>(db);
|
|
storeRequest.<a>onsuccess</a> =
|
|
function() {
|
|
var store = storeRequest.<a>store</a>, total = 0;
|
|
var cursorRequest = new <a>IDBCursorRequest</a>(store);
|
|
cursorRequest.<a>onsuccess</a> =
|
|
function() {
|
|
span.textContent = total;
|
|
};
|
|
cursorRequest.<a>open</a>(function(record, cursor) {
|
|
total += cursor.<a>count</a>;
|
|
}, <a>IDBCursor</a>.<a>NEXT_NO_DUPLICATE</a>);
|
|
};
|
|
storeRequest.<a>open</a>('docids', true);
|
|
};
|
|
|
|
prepareDatabase(function(evt) {
|
|
// got database
|
|
var span = document.getElementById('doc-count');
|
|
showDocCount(request.<a>database</a>, span);
|
|
}, function (evt) {
|
|
// error getting database
|
|
var error = request.error;
|
|
alert(error.message);
|
|
});</codeblock>
|
|
</div>-->
|
|
</div>
|
|
|
|
<div id="conformance" class="section"><!--OddPage--><h2><span class="secno">2. </span>Conformance</h2><p>As
|
|
well as sections marked as non-normative, all authoring guidelines,
|
|
diagrams, examples, and notes in this specification are non-normative.
|
|
Everything else in this specification is normative.</p>
|
|
<p>The key words <em title="must" class="rfc2119">must</em>, <em title="must not" class="rfc2119">must not</em>, <em title="required" class="rfc2119">required</em>, <em title="should" class="rfc2119">should</em>, <em title="should not" class="rfc2119">should not</em>, <em title="recommended" class="rfc2119">recommended</em>, <em title="may" class="rfc2119">may</em>, and <em title="optional" class="rfc2119">optional</em> in this specification are to be interpreted as described in [<cite><a href="#bib-RFC2119" rel="biblioentry" class="bibref">RFC2119</a></cite>].</p>
|
|
|
|
<p>
|
|
This specification defines one class of products:
|
|
</p>
|
|
<dl>
|
|
<dt><dfn id="dfn-conforming-user-agent">Conforming user agent</dfn></dt>
|
|
<dd>
|
|
<p>
|
|
A user agent <em title="must" class="rfc2119">must</em> behave as described in this specification
|
|
in order to be considered conformant.
|
|
</p>
|
|
|
|
<p>
|
|
User agents <em title="may" class="rfc2119">may</em> implement algorithms given in this
|
|
specification in any way desired, so long as the end result is
|
|
indistinguishable from the result that would be obtained by the
|
|
specification's algorithms.
|
|
</p>
|
|
|
|
<p>
|
|
A conforming Indexed Database API user agent <em title="must" class="rfc2119">must</em> also be a
|
|
<em>conforming implementation</em> of the IDL fragments
|
|
of this specification, as described in the
|
|
“Web IDL” specification. [<cite><a href="#bib-WEBIDL" rel="biblioentry" class="bibref">WEBIDL</a></cite>]
|
|
</p>
|
|
|
|
<div class="note">
|
|
This specification uses both the terms "conforming user agent(s)"
|
|
and "user agent(s)" to refer to this product class.
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
|
|
<div class="section" id="dependencies">
|
|
<h3><span class="secno">2.1 </span>Dependencies</h3>
|
|
<p>
|
|
This specification relies on several other underlying specifications.
|
|
</p>
|
|
<dl>
|
|
<dt>DOM-LEVEL-3-EVENTS</dt>
|
|
<dd>The terms <dfn id="dfn-default-action">default action</dfn> and <dfn id="dfn-propagation-path">propagation path</dfn> are defined by the
|
|
Document Object Model (DOM) Level 3 Events Specification [<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>].
|
|
</dd>
|
|
<dt>HTML5</dt>
|
|
<dd>The terms and algorithms <dfn id="document-base-url">document base URL</dfn>,
|
|
<dfn id="event-handler-attributes">event handler attributes</dfn>,
|
|
<dfn id="event-handler-event-type">event handler event type</dfn>,
|
|
<dfn id="dfn-function" title="Function"><code>Function</code></dfn>,
|
|
<dfn id="dfn-origin">origin</dfn>, <dfn id="dfn-same-origin">same origin</dfn>, <dfn id="dfn-structured-clone">structured clone</dfn>,
|
|
<dfn id="dfn-structured-clone-algorithm">structured clone algorithm</dfn>, <dfn id="dfn-task">task</dfn>, <dfn id="dfn-task-source">task source</dfn>,
|
|
and <dfn id="dfn-queue-a-task" title="queue-a-task">queue a task</dfn> are defined by the HTML 5
|
|
specification [<cite><a href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a></cite>].
|
|
</dd>
|
|
<dt>WebIDL</dt>
|
|
<dd>Many of the interface definitions and all of the IDL in this spec depends on [[!!WEBIDL]].</dd>
|
|
<dt>WebWorkers</dt>
|
|
<dd>The term <dfn id="dfn-worker" title="Worker"><a class="externalDFN"><code>Worker</code></a></dfn> is defined by
|
|
the WebWorkers specification [<cite><a href="#bib-WEBWORKERS" rel="biblioentry" class="bibref">WEBWORKERS</a></cite>].</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div id="database-api" class="section">
|
|
<!--OddPage--><h2><span class="secno">3. </span>Indexed Database API</h2>
|
|
<div id="constructs" class="section">
|
|
<h3><span class="secno">3.1 </span>Constructs</h3>
|
|
<div id="database-concept" class="section">
|
|
<h4><span class="secno">3.1.1 </span>Database</h4>
|
|
<p>
|
|
Each <a class="internalDFN" href="#dfn-origin">origin</a> has an associated set of
|
|
<a class="internalDFN" href="#dfn-database" title="database">databases</a>. A <dfn id="dfn-database">database</dfn> comprises
|
|
one or more <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> which hold the data stored
|
|
in the database.
|
|
</p>
|
|
<p>
|
|
Every <a class="internalDFN" href="#dfn-database">database</a> has a <dfn id="dfn-database-name" title="database name">name</dfn> which identifies it
|
|
within a specific <a class="internalDFN" href="#dfn-origin">origin</a>. The name can be any string value, including the empty string, and
|
|
stays constant for the lifetime of the database. Each <a class="internalDFN" href="#dfn-database">database</a> also has a current
|
|
<dfn id="dfn-version">version</dfn>. When a database is first created, its <a class="internalDFN" href="#dfn-version">version</a> is 0.
|
|
</p>
|
|
<p class="note">
|
|
Implementations <em title="must" class="rfc2119">must</em> support all names. If an implementation
|
|
uses a storage mechanism which can't handle arbitrary database names,
|
|
the implementation must use an escaping mechanism or something similar
|
|
to map the provided name to a name that it can handle.
|
|
</p>
|
|
<p class="note">
|
|
Each <a class="internalDFN" href="#dfn-database">database</a> has one version at a time; a <a class="internalDFN" href="#dfn-database">database</a>
|
|
can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</p>
|
|
<p>
|
|
Databases has a <dfn id="dfn-delete-pending">delete pending</dfn> flag which is used during deletion. When a database is requested
|
|
to be deleted the flag is set to true and all attempts at opening the database are stalled until the database
|
|
can be deleted.
|
|
</p>
|
|
<p>
|
|
The act of opening a <a class="internalDFN" href="#dfn-database">database</a> creates a <dfn id="dfn-connection">connection</dfn>. There <em title="may" class="rfc2119">may</em> be multiple
|
|
<a class="internalDFN" href="#dfn-connection">connection</a>s to a given <a class="internalDFN" href="#dfn-database">database</a> at any given time. Each connection has a
|
|
<dfn id="dfn-closepending">closePending</dfn> flag which initially is set to false.
|
|
</p>
|
|
<p>
|
|
When a <a class="internalDFN" href="#dfn-connection">connection</a> is initially created it is in <var>opened</var> state. The connection
|
|
can be <dfn id="dfn-database-close" title="database close">closed</dfn> through several means. If the connection is GCed
|
|
or execution context where the <a class="internalDFN" href="#dfn-connection">connection</a> is created is destroyed (for example due to the
|
|
user navigating away from that page), the connection is closed. The connection can also be closed
|
|
explicitly using the <a class="internalDFN" href="#dfn-steps-for-closing-a-database-connection">steps for closing a database connection</a>. When the connection is closed
|
|
the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is always set to true if it hasn't already been.
|
|
</p>
|
|
<p>
|
|
The <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> and <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a>
|
|
interfaces represent a <a class="internalDFN" href="#dfn-connection">connection</a> to a <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</p>
|
|
</div> <!-- IDBDatabase -->
|
|
|
|
<div class="section" id="object-store-concept">
|
|
<h4><span class="secno">3.1.2 </span>Object Store</h4>
|
|
<p>
|
|
An <dfn id="dfn-object-store">object store</dfn> is the primary storage mechanism for storing data in a
|
|
<a class="internalDFN" href="#dfn-database">database</a>.
|
|
</p>
|
|
<p>
|
|
Each database contain a set of <a class="internalDFN" href="#dfn-object-store">object store</a>s. The set of <a class="internalDFN" href="#dfn-object-store">object store</a>s
|
|
can be changed, but can only be changed using a VERSION_CHANGE transactions. When a new database is
|
|
created it doesn't contain any <a class="internalDFN" href="#dfn-object-store">object store</a>s and has the empty string as <a class="internalDFN" href="#dfn-version">version</a>.
|
|
</p>
|
|
<p>
|
|
The object store has a <a title="object store record list">list of records</a> which hold the
|
|
data stored in the object store. Each <dfn id="dfn-record">record</dfn> consists of a <dfn id="dfn-key">key</dfn> and a <dfn id="dfn-value">value</dfn>.
|
|
The list is sorted according to key in ascending order. There can never be multiple records in a given object
|
|
store with the same key.
|
|
</p>
|
|
<p>
|
|
Every <a class="internalDFN" href="#dfn-object-store">object store</a> has a <dfn id="dfn-object-store-name" title="object store name">name</dfn>.
|
|
The name is unique within the <a class="internalDFN" href="#dfn-database">database</a> to which it belongs. Every object store also optionally has a
|
|
<a class="internalDFN" href="#dfn-key-generator">key generator</a> and an optional <dfn id="dfn-object-store-key-path" title="object store key path">key path</dfn>.
|
|
If the object store has a key path it is said to use <dfn id="dfn-in-line-keys">in-line keys</dfn>. Otherwise it is said to
|
|
use <dfn id="dfn-out-of-line">out-of-line</dfn> keys.
|
|
</p>
|
|
<p>
|
|
The object store can derive the <a class="internalDFN" href="#dfn-key-1">key</a> from one of three sources. Which source is used is determined
|
|
when the object store is created. The three sources are:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
A <dfn id="dfn-key-generator">key generator</dfn>. A key generator generates a monotonically increasing numbers every time
|
|
a key is needed.
|
|
<p class="issue">
|
|
specify that generators are not shared between stores.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
Keys can be derived via a <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a>.
|
|
</li>
|
|
<li>
|
|
Keys can also be explicitly specified when a <a class="internalDFN" href="#dfn-value-1">value</a> is stored in the object store.
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
The <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> and <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a>
|
|
interfaces represent an <a class="internalDFN" href="#dfn-object-store">object store</a>. Note however that multiple instances of those
|
|
interfaces representing the same <a class="internalDFN" href="#dfn-object-store">object store</a> can exist.
|
|
</p>
|
|
</div> <!-- Object store -->
|
|
|
|
<div id="key-construct" class="section">
|
|
<h4><span class="secno">3.1.3 </span>Keys</h4>
|
|
<p>
|
|
In order to efficiently retrieve <a class="internalDFN" href="#dfn-record">record</a>s stored in an indexed database,
|
|
each <a class="internalDFN" href="#dfn-record">record</a> is organized according to its <dfn id="dfn-key-1">key</dfn>. A value is said to be a <dfn id="dfn-valid-key">valid key</dfn>
|
|
if it is one of the following types:
|
|
<code>Array</code> JavaScript objects [<cite><a href="#bib-ECMA-262" rel="biblioentry" class="bibref">ECMA-262</a></cite>], <code>DOMString</code> [<cite><a href="#bib-WEBIDL" rel="biblioentry" class="bibref">WEBIDL</a></cite>],
|
|
<code>Date</code> [<cite><a href="#bib-ECMA-262" rel="biblioentry" class="bibref">ECMA-262</a></cite>] or <code>float</code> [<cite><a href="#bib-WEBIDL" rel="biblioentry" class="bibref">WEBIDL</a></cite>].
|
|
However <code>Array</code>s are only <a class="internalDFN" href="#dfn-valid-key">valid key</a>s if every item in the array is defined and is
|
|
a <a class="internalDFN" href="#dfn-valid-key">valid key</a> (i.e. sparse arrays can not be <a class="internalDFN" href="#dfn-valid-key">valid key</a>s).
|
|
Any non-numeric properties are ignored, and thus does not affect if the <code>Array</code> is a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
Additionally, if the value is of type <code>float</code>, it is only a <a class="internalDFN" href="#dfn-valid-key">valid key</a> if it is not NaN.
|
|
<a>Conforming user agents</a> <em title="must" class="rfc2119">must</em> support all <a class="internalDFN" href="#dfn-valid-key">valid key</a>s as keys.
|
|
</p>
|
|
<p class="note">
|
|
Infinite <code>float</code> values are <a class="internalDFN" href="#dfn-valid-key">valid key</a>s. As are empty <code>Array</code>s.
|
|
</p>
|
|
<p>
|
|
For purposes of comparison, all <code>Array</code>s are greater than all <code>DOMString</code>,
|
|
<code>Date</code> and <code>float</code> values; all <code>DOMString</code> values are greater than all
|
|
<code>Date</code> and <code>float</code> values; and all <code>Date</code> values are greater than all
|
|
<code>float</code> values. Values of type <code>float</code> are compared to other <code>float</code> values
|
|
numerically. Values of type <code>Date</code> are compared to other <code>Date</code> values chronologically.
|
|
Values of type <code>DOMString</code> are compared to other values of type <code>DOMString</code>
|
|
by using the algorithm defined by step 4 of <cite>section 11.8.5, The Abstract Relational Comparison Algorithm</cite>,
|
|
of the ECMAScript Language Specification [<cite><a href="#bib-ECMA-262" rel="biblioentry" class="bibref">ECMA-262</a></cite>].
|
|
Values of type <code>Array</code> are compared to other values of type <code>Array</code> as follows:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Let <var>A</var> be the first <code>Array</code> value and <var>B</var> be the second <code>Array</code>
|
|
value.
|
|
</li>
|
|
<li>
|
|
Let <var>length</var> be the lesser of <var>A</var>'s length and <var>B</var>'s length.
|
|
</li>
|
|
<li>
|
|
Let <var>i</var> be 0.
|
|
</li>
|
|
<li>
|
|
If the <var>i</var>th value of <var>A</var> is <a class="internalDFN" href="#dfn-less-than">less than</a> the <var>i</var>th value of
|
|
<var>B</var>, then <var>A</var> is less than <var>B</var>. Skip the remaining steps.
|
|
</li>
|
|
<li>
|
|
If the <var>i</var>th value of <var>A</var> is <a class="internalDFN" href="#dfn-greater-than">greater than</a> the <var>i</var>th value of
|
|
<var>B</var>, then <var>A</var> is greater than <var>B</var>. Skip the remaining steps.
|
|
</li>
|
|
<li>
|
|
Increase <var>i</var> by 1.
|
|
</li>
|
|
<li>
|
|
If <var>i</var> is not equal to <var>length</var>, go back to step 4. Otherwise continue to next step.
|
|
</li>
|
|
<li>
|
|
If <var>A</var>'s length is less than <var>B</var>'s length, then <var>A</var> is less
|
|
than <var>B</var>. If <var>A</var>'s length is greater than <var>B</var>'s length, then
|
|
<var>A</var> is greater than <var>B</var>. Otherwise <var>A</var> and <var>B</var> are equal.
|
|
</li>
|
|
</ol>
|
|
<p class="note">
|
|
Note that <code>Array</code>s that contain other <code>Array</code>s are allowed as <a class="internalDFN" href="#dfn-valid-key">valid key</a>s.
|
|
In this case the algorithm above runs recursively when comparing the individual values in the arrays.
|
|
</p>
|
|
<p class="note">
|
|
As a result of the above rules, negative infinity is the lowest possible value for a key.
|
|
There is no highest possible key value.
|
|
This is because an array of any candidate highest key followed by another valid key is even higher.
|
|
</p>
|
|
<p>
|
|
The terms <dfn id="dfn-greater-than">greater than</dfn>, <dfn id="dfn-less-than">less than</dfn> and <dfn id="dfn-equal-to">equal to</dfn> is defined in the terms of
|
|
the above comparisons.
|
|
</p>
|
|
<p>
|
|
The following examples illustrate the different behaviors when trying to use in-line <a class="internalDFN" href="#dfn-key-1">key</a>s and <a class="internalDFN" href="#dfn-key-generator">key generator</a>s
|
|
to save an object to an <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
<div class="example"><div class="exampleHeader">Example</div>
|
|
<p>If the following conditions are true:</p>
|
|
<ul>
|
|
<li>This is the fourth entry in an <a class="internalDFN" href="#dfn-object-store">object store</a>.</li>
|
|
<li>The <a class="internalDFN" href="#dfn-object-store">object store</a> has a <a class="internalDFN" href="#dfn-key-generator">key generator</a>.</li>
|
|
<li>There is no in-line value for the <a class="internalDFN" href="#dfn-key-path">key path</a> property.</li>
|
|
</ul>
|
|
<p>
|
|
Then the value provided by the <a class="internalDFN" href="#dfn-key-generator">key generator</a> is used to populate the key value.
|
|
In the example below the <a class="internalDFN" href="#dfn-key-path">key path</a> for the object store is <code>"foo.bar"</code>.
|
|
The actual object has no value for the <code>bar</code> property, <code>{ foo: {} }</code>.
|
|
When the object is saved in the <a class="internalDFN" href="#dfn-object-store">object store</a> the <code>bar</code> property is assigned a value of 4
|
|
because that is the next <a class="internalDFN" href="#dfn-key-1">key</a> generated by the <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
|
|
"foo.bar"
|
|
{ foo: {} }
|
|
</code></pre></div></div>
|
|
<p>If the following conditions are true:</p>
|
|
<ul>
|
|
<li>This is the fourth entry in an <a class="internalDFN" href="#dfn-object-store">object store</a>.</li>
|
|
<li>The <a class="internalDFN" href="#dfn-object-store">object store</a> has a <a class="internalDFN" href="#dfn-key-generator">key generator</a>.</li>
|
|
<li>There is a value for the <a class="internalDFN" href="#dfn-key-path">key path</a> property.</li>
|
|
</ul>
|
|
<p>
|
|
Then the value associated with the <a class="internalDFN" href="#dfn-key-path">key path</a> property is used.
|
|
The auto-generated <a class="internalDFN" href="#dfn-key-1">key</a> is not used.
|
|
In the example below the <a>keypath</a> for the <a class="internalDFN" href="#dfn-object-store">object store</a> is <code>"foo.bar"</code>.
|
|
The actual object has a value of 10 for the <code>bar</code> property, <code>{ foo: { bar: 10} }</code>.
|
|
When the object is saved in the <a class="internalDFN" href="#dfn-object-store">object store</a> the <code>bar</code> property keeps its value of 10, because that is the <a>key value</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
|
|
"foo.bar"
|
|
{ foo: { bar: 10 } }
|
|
</code></pre></div></div>
|
|
<p>
|
|
The following example illustrates the scenario when the specified in-line <a class="internalDFN" href="#dfn-key-1">key</a> is defined through a <a class="internalDFN" href="#dfn-key-path">key path</a> but there is no property matching it.
|
|
The value provided by the <a class="internalDFN" href="#dfn-key-generator">key generator</a> is then used to populate the <a>key value</a> and the system is responsible
|
|
for creating as many properties as it requires to suffice the property dependencies on the hierarchy chain.
|
|
In the example below the <a class="internalDFN" href="#dfn-key-path">key path</a> for the <a class="internalDFN" href="#dfn-object-store">object store</a> is <code>"foo.bar.baz"</code>.
|
|
The actual object has no value for the <code>foo</code> property, <code>{ zip: {} }</code>.
|
|
When the object is saved in the <a class="internalDFN" href="#dfn-object-store">object store</a> the <code>foo</code>, <code>bar</code>, and <code>baz</code> properties
|
|
are created each as a child of the other until a value for <code>foo.bar.baz</code> can be assigned.
|
|
The value for <code>foo.bar.baz</code> is the next key generated by the object store.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
|
|
"foo.bar.baz"
|
|
{ zip: {} }
|
|
</code></pre></div></div>
|
|
<p>
|
|
Attempting to store a property on a primitive value will fail and throw an error.
|
|
In the first example below the <a class="internalDFN" href="#dfn-key-path">key path</a> for the object store is <code>"foo"</code>.
|
|
The actual object is a primitive with the value, 4.
|
|
Trying to define a property on that primitive value fails.
|
|
The same is true for arrays. Properties are not allowed on an array.
|
|
In the second example below, the actual object is an array, [10].
|
|
Trying to define a property on the array fails.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
|
|
// The key generation will attempt to create and store the key path property on this primitive.
|
|
"foo"
|
|
4
|
|
|
|
// The key generation will attempt to create and store the key path property on this array.
|
|
"foo"
|
|
[10]
|
|
|
|
</code></pre></div></div>
|
|
|
|
</div></div>
|
|
|
|
<div id="value-construct" class="section">
|
|
<h4><span class="secno">3.1.4 </span>Values</h4>
|
|
<p>
|
|
Each record is associated with a <dfn id="dfn-value-1">value</dfn>. <a>Conforming user agents</a> <em title="must" class="rfc2119">must</em> support
|
|
any value supported by the <a class="internalDFN" href="#dfn-structured-clone-algorithm">structured clone algorithm</a>
|
|
[<cite><a href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a></cite>]. This includes simple types such as <code>DOMString</code>
|
|
and <code>Date</code> as well as <code>Object</code> and <code>Array</code>
|
|
instances.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="key-path-construct" class="section">
|
|
<h4><span class="secno">3.1.5 </span>Key Path</h4>
|
|
<p>
|
|
A <dfn id="dfn-key-path">key path</dfn> is a <code>DOMString</code> that defines how to extract a <a class="internalDFN" href="#dfn-key-1">key</a> from a <a class="internalDFN" href="#dfn-value-1">value</a>.
|
|
A <dfn id="dfn-valid-key-path">valid key path</dfn> is
|
|
either the empty string, a JavaScript identifier, or multiple Javascript identifiers separated by
|
|
periods (ASCII character code 46) [<cite><a href="#bib-ECMA-262" rel="biblioentry" class="bibref">ECMA-262</a></cite>]. (Note that spaces are not allowed
|
|
within a key path.) To <dfn id="dfn-evaluate-key-path" title="evaluate key path">evaluate a key path</dfn>, run the
|
|
<a class="internalDFN" href="#dfn-steps-for-extracting-a-key-from-a-value-using-a-key-path">steps for extracting a key from a value using a key path</a>.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="index-concept" class="section">
|
|
<h4><span class="secno">3.1.6 </span>Index</h4>
|
|
<p>
|
|
It is sometimes useful to retrieve <a>records</a> in an <a class="internalDFN" href="#dfn-object-store">object store</a> through other means
|
|
than their <a class="internalDFN" href="#dfn-key-1">key</a>. An <dfn id="dfn-index">index</dfn> allows looking up <a class="internalDFN" href="#dfn-record">record</a>s in an <a class="internalDFN" href="#dfn-object-store">object store</a>
|
|
using properties of the <a class="internalDFN" href="#dfn-value-1">value</a>s in the <a class="internalDFN" href="#dfn-object-store">object store</a>s <a class="internalDFN" href="#dfn-record">record</a>s.
|
|
</p>
|
|
<p>
|
|
An index is a specialized persistent key-value storage and has a <dfn id="dfn-referenced">referenced</dfn> <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
The index has a <dfn id="dfn-index-record-list" title="index record list">list of records</dfn> which hold the
|
|
data stored in the index. The records in an index are automatically populated whenever records in the
|
|
<a class="internalDFN" href="#dfn-referenced">referenced</a> object store are inserted, updated or deleted. There can be several <a class="internalDFN" href="#dfn-index">index</a>es
|
|
referencing the same <a class="internalDFN" href="#dfn-object-store">object store</a>, in which changes to the object store cause all such indexes
|
|
to get updated.
|
|
</p>
|
|
<p>
|
|
The values in the index's <a class="internalDFN" href="#dfn-record">record</a>s are always values of <a>keys</a> in the index's <a class="internalDFN" href="#dfn-referenced">referenced</a>
|
|
object store. The keys are derived from the referenced object store's <a class="internalDFN" href="#dfn-value-1">value</a>s using a <dfn id="dfn-index-key-path" title="index key path"><a class="internalDFN" href="#dfn-key-path">key path</a></dfn>.
|
|
If a given <a class="internalDFN" href="#dfn-record">record</a> with key <var>X</var> in the object store referenced by the index has the value <var>A</var>, and
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the <a class="internalDFN" href="#dfn-index-key-path" title="index key path">index's key path</a> on <var>A</var> yields the result
|
|
<var>Y</var>, then the index will contain a record with key <var>Y</var> and value <var>X</var>.
|
|
</p>
|
|
<p>
|
|
Records in an index are said to have a <dfn id="dfn-referenced-value">referenced value</dfn>. This is the value of the record in the index's referenced
|
|
object store which has a key equal to the index's record's value. So in the example above,
|
|
the record in the index whose key is <var>Y</var> and value is <var>X</var> has a <a class="internalDFN" href="#dfn-referenced-value">referenced value</a> of <var>A</var>.
|
|
</p>
|
|
<p class="note">
|
|
Each record in an index reference one and only one record in the index's <a class="internalDFN" href="#dfn-referenced">referenced</a>
|
|
object store. However there can be
|
|
multiple records in an index which reference the same record
|
|
in the object store. And there can also be no records in an index
|
|
which reference a given record in an object store.
|
|
</p>
|
|
<p>
|
|
The <a class="internalDFN" href="#dfn-record">record</a>s in an index are always sorted according to the <a class="internalDFN" href="#dfn-record">record</a>s key. However unlike object stores,
|
|
a given index can contain multiple records with the same key. Such records are additionally sorted according to
|
|
the records value.
|
|
</p>
|
|
<p>
|
|
An index contains a <dfn id="dfn-unique">unique</dfn> flag. When this flag is set to true, the index enforces that no two <a class="internalDFN" href="#dfn-record">record</a>s
|
|
in the index has the same key. If a <a class="internalDFN" href="#dfn-record">record</a>
|
|
in the index's referenced object store is attempted to be inserted or
|
|
modified such that evaluating the index's key path on the
|
|
records new value yields a result which already exists in the
|
|
index, then the attempted modification to the object store
|
|
fails.
|
|
</p>
|
|
<p>
|
|
An index also contains a <dfn id="dfn-multientry">multientry</dfn> flag. This flag affects how the index behaves when the result of evaluating
|
|
the index's <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> yields an <code>Array</code>. If the <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is false, then
|
|
a single <a class="internalDFN" href="#dfn-record">record</a> whose <a class="internalDFN" href="#dfn-key-1">key</a> is an <code>Array</code> is added to the index. If the <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is
|
|
true, then the one <a class="internalDFN" href="#dfn-record">record</a> is added to the index for each item in the <code>Array</code>. The <a class="internalDFN" href="#dfn-key-1">key</a> for each
|
|
record is the value of respective item in the <code>Array</code>.
|
|
</p>
|
|
<p>
|
|
The <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> and <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> interfaces
|
|
provide access to the metadata of an <a class="internalDFN" href="#dfn-index">index</a>. Note however that multiple instances of those
|
|
interfaces representing the same <a class="internalDFN" href="#dfn-index">index</a> can exist.
|
|
</p>
|
|
</div> <!-- IDBIndex -->
|
|
|
|
<div id="transaction-concept" class="section">
|
|
<h4><span class="secno">3.1.7 </span>Transaction</h4>
|
|
<p>
|
|
A <dfn id="dfn-transaction">transaction</dfn> is used to interact with the data in a <a class="internalDFN" href="#dfn-database">database</a>.
|
|
Whenever data is read or written to the database it is done by using a <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</p>
|
|
<p>
|
|
All transactions are created through a <a class="internalDFN" href="#dfn-connection">connection</a>, which is the transaction's
|
|
<dfn id="dfn-transaction-connection" title="transaction connection">connection</dfn>.
|
|
The transaction has a <a class="internalDFN" href="#dfn-mode">mode</a> that determines which types of interactions can be performed
|
|
upon that transaction. The <a class="internalDFN" href="#dfn-mode">mode</a> is set when the transaction is created and remains
|
|
fixed for the life of the transaction. The transaction also has a <dfn id="dfn-scope">scope</dfn> that
|
|
determines the <a class="internalDFN" href="#dfn-object-store">object store</a>s with which the transaction may interact. Transactions
|
|
have an <dfn id="dfn-active">active</dfn> flag, which determines if new <a class="internalDFN" href="#dfn-request">request</a>s can be made
|
|
against the transaction. Finally, transactions also contain a <dfn id="dfn-request-list">request list</dfn> of
|
|
<a class="internalDFN" href="#dfn-request">request</a>s which have been made against the transaction.
|
|
</p>
|
|
<p>
|
|
Each transaction has a fixed scope, determined when the transaction is created.
|
|
A transaction's scope remains fixed for the lifetime of that transaction.
|
|
</p>
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-transaction" title="transaction">Transactions</a> offer some protection from
|
|
application and system failures. A <a class="internalDFN" href="#dfn-transaction">transaction</a> may be used to
|
|
store multiple data records or to conditionally modify certain data
|
|
records. A <a class="internalDFN" href="#dfn-transaction">transaction</a> represents an atomic and durable set
|
|
of data access and data mutation operations.
|
|
</p>
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-transaction" title="transaction">Transactions</a> are expected to be short lived. This is encouraged
|
|
by the <a class="internalDFN" href="#dfn-commit" title="commit">automatic committing</a> functionality described below. Authors can still cause
|
|
transactions to run for a long time; however, this usage pattern
|
|
is not generally recommended as it can lead to a bad user experience.
|
|
</p>
|
|
<p>
|
|
The <dfn id="dfn-transaction-lifetime" title="transaction lifetime">lifetime</dfn> of a <a class="internalDFN" href="#dfn-transaction">transaction</a> is as follows:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
A transaction is <dfn id="dfn-transaction-create" title="transaction create">created</dfn> using
|
|
<a class="idlType" href="#widl-IDBDatabase-transaction-IDBTransaction-any-storeNames-unsigned-short-mode">IDBDatabase.transaction</a>.
|
|
The arguments passed determine the <a class="internalDFN" href="#dfn-scope">scope</a> of the transaction and whether the transaction is read-only.
|
|
When a transaction is created its <a class="internalDFN" href="#dfn-active">active</a> flag is initially set to true.
|
|
</li>
|
|
<li>
|
|
The implementation <em title="must" class="rfc2119">must</em> allow <a class="internalDFN" href="#dfn-request">request</a>s to be <a class="internalDFN" href="#dfn-place-request" title="place request">placed</a> against the transaction
|
|
whenever the <a class="internalDFN" href="#dfn-active">active</a> flag is true. This is the case even if the transaction has not yet been
|
|
<a class="internalDFN" href="#dfn-transaction-start" title="transaction start">started</a>. Until the transaction is <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">started</a>
|
|
the implementation <em title="must not" class="rfc2119">must not</em> execute these requests; however, the implementation <em title="must" class="rfc2119">must</em> keep track of the
|
|
<a class="internalDFN" href="#dfn-request">request</a>s and their order. Requests may be placed against a transaction only while that transaction
|
|
is <a class="internalDFN" href="#dfn-active">active</a>. If an attempt is made to place a request against a transaction when that transaction is not
|
|
<a class="internalDFN" href="#dfn-active">active</a>, the implementation <em title="must" class="rfc2119">must</em> reject the attempt by throwing a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-transactioninactiveerror"><code>TransactionInactiveError</code></a>.
|
|
</li>
|
|
<li>
|
|
Once an implementation is able to enforce the constraints defined for the transaction <a class="internalDFN" href="#dfn-mode">mode</a>, defined below,
|
|
the implementation <em title="must" class="rfc2119">must</em> queue up an operation to <dfn id="dfn-transaction-start" title="transaction start">start</dfn> the transaction asynchronously.
|
|
The timing for when this happens is affected by:
|
|
<ul>
|
|
<li>The <a class="internalDFN" href="#dfn-mode">mode</a> in which the transaction is opened.</li>
|
|
<li>Which <a class="internalDFN" href="#dfn-object-store">object store</a>s are included in the <a class="internalDFN" href="#dfn-scope">scope</a> of the transaction.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
Once the transaction has been <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">started</a> the implementation can
|
|
start executing the <a class="internalDFN" href="#dfn-request">request</a>s placed against the transaction. Unless otherwise defined, requests
|
|
<em title="must" class="rfc2119">must</em> be executed in the order in which they were made against the transaction. Likewise, their results <em title="must" class="rfc2119">must</em>
|
|
be returned in the order the requests were placed against a specific transaction.
|
|
There is no guarantee about the order that results from requests in different transactions are returned.
|
|
Similarly, the transaction <a class="internalDFN" href="#dfn-mode">mode</a>s ensure that two requests placed against different transactions
|
|
can execute in any order without affecting what resulting data is stored in the database.
|
|
</li>
|
|
<li>
|
|
A transaction can be <dfn id="dfn-abort" title="abort">aborted</dfn> at any time before it is <a title="transaction finish">finished</a>,
|
|
even if the transaction isn't currently <a class="internalDFN" href="#dfn-active">active</a> or hasn't yet <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">started</a>.
|
|
When a transaction is aborted the implementation <em title="must" class="rfc2119">must</em> undo (roll back) any changes
|
|
that were made to the <a class="internalDFN" href="#dfn-database">database</a> during that transaction. This includes both changes to the contents of
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>s as well as additions and removals of <a class="internalDFN" href="#dfn-object-store">object store</a>s and <a class="internalDFN" href="#dfn-index">index</a>es.
|
|
</li>
|
|
<li>
|
|
When a transaction can no longer become <a class="internalDFN" href="#dfn-active">active</a>, the implementation <em title="must" class="rfc2119">must</em> attempt to
|
|
<dfn id="dfn-commit">commit</dfn> it, as long as the transaction has not been <a class="internalDFN" href="#dfn-abort" title="abort">aborted</a>.
|
|
This usually happens after all requests placed against the
|
|
transaction have been executed and their returned results handled, and no new requests have been placed
|
|
against the transaction. When a transaction is committed, the implementation <em title="must" class="rfc2119">must</em> atomically write
|
|
any changes to the <a class="internalDFN" href="#dfn-database">database</a> made by requests placed against the transaction. That is, either all
|
|
of the changes <em title="must" class="rfc2119">must</em> be written, or if an error occurs, such as a disk write error, the implementation
|
|
<em title="must not" class="rfc2119">must not</em> write any of the changes to the database. If such an error occurs, the implementation <em title="must" class="rfc2119">must</em>
|
|
<a class="internalDFN" href="#dfn-abort">abort</a> the transaction by following the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>, otherwise it
|
|
<em title="must" class="rfc2119">must</em> <a class="internalDFN" href="#dfn-commit">commit</a> the transaction by following the <a class="internalDFN" href="#dfn-steps-for-committing-a-transaction">steps for committing a transaction</a>.
|
|
</li>
|
|
<li>
|
|
When a transaction is <a class="internalDFN" href="#dfn-commit">commit</a>ted or <a class="internalDFN" href="#dfn-abort">abort</a>ed, it is said to be
|
|
<dfn title="transaction finish">finished</dfn>. If a transaction can't be finished, for example
|
|
due to the implementation crashing or the user taking some explicit action to cancel it, the
|
|
implementation <em title="must" class="rfc2119">must</em> <a class="internalDFN" href="#dfn-abort">abort</a> the transaction.
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
Transactions are opened in one of three <dfn id="dfn-mode" title="mode">modes</dfn>. The mode
|
|
determines how concurrent access to <a class="internalDFN" href="#dfn-object-store">object store</a>s in the transaction are isolated.
|
|
</p>
|
|
<ol>
|
|
<li><code><dfn id="dfn-read_only">READ_ONLY</dfn></code></li>
|
|
<li><code><dfn id="dfn-read_write">READ_WRITE</dfn></code></li>
|
|
<li><code><dfn id="dfn-version_change">VERSION_CHANGE</dfn></code></li>
|
|
</ol>
|
|
|
|
<p>
|
|
The transaction <a class="internalDFN" href="#dfn-mode">mode</a> controls whether or not multiple transactions can run currently
|
|
and which operations may be performed during the transaction.
|
|
The allowed operations are defined in detail below, but in general
|
|
transactions opened in <code><a class="internalDFN" href="#dfn-read_only">READ_ONLY</a></code> mode are only allowed to perform
|
|
operations that do not change data. READ_WRITE transactions are allowed to
|
|
read from and write to transactions to existing <a class="internalDFN" href="#dfn-object-store">object store</a>s, whereas
|
|
VERSION_CHANGE transactions are allowed to perform any operations, including ones that
|
|
delete and create <a class="internalDFN" href="#dfn-object-store">object store</a>s and <a class="internalDFN" href="#dfn-index">index</a>es.
|
|
</p>
|
|
|
|
<p>
|
|
A VERSION_CHANGE transaction can never run concurrently with other transactions. When
|
|
a VERSION_CHANGE transaction is created, the implementation <em title="must" class="rfc2119">must</em> wait to
|
|
<a class="internalDFN" href="#dfn-transaction-start" title="transaction start">start</a> the VERSION_CHANGE transaction until no other transactions
|
|
against the same <a class="internalDFN" href="#dfn-database">database</a> are running. As long as the VERSION_CHANGE transaction is pending, the implementation
|
|
<em title="must" class="rfc2119">must</em> wait before <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">starting</a> any other transactions against the same <a class="internalDFN" href="#dfn-database">database</a>
|
|
until the VERSION_CHANGE transaction is finished.
|
|
</p>
|
|
<p>
|
|
Any number of transactions opened in <a class="internalDFN" href="#dfn-read_only">READ_ONLY</a> mode are allowed to run concurrently,
|
|
even if the transaction's <a class="internalDFN" href="#dfn-scope">scope</a> overlap and include the same <a class="internalDFN" href="#dfn-object-store">object store</a>s.
|
|
As long as a READ_ONLY transaction is running, the data that the implementation returns
|
|
through <a class="internalDFN" href="#dfn-request">request</a>s created with that transaction <em title="must" class="rfc2119">must</em> remain
|
|
constant. That is, two requests to read the same piece of data <em title="must" class="rfc2119">must</em> yield the same result
|
|
both for the case when data is found and the result is that data, and for the case when data
|
|
is not found and a lack of data is indicated.
|
|
</p>
|
|
<p>
|
|
There are a number of ways that an implementation ensures this. The implementation can prevent any
|
|
READ_WRITE transaction, whose scope overlaps the scope of the READ_ONLY transaction, from
|
|
starting until the READ_ONLY transaction finishes. Or the implementation can allow the READ_ONLY
|
|
transaction to see a snapshot of the contents of the <a class="internalDFN" href="#dfn-object-store">object store</a>s which is taken when
|
|
the READ_ONLY transaction started.
|
|
</p>
|
|
<p>
|
|
Similarly, implementations <em title="must" class="rfc2119">must</em> ensure that a READ_WRITE transaction is only affected by
|
|
changes to <a class="internalDFN" href="#dfn-object-store">object store</a>s that are made using the transaction itself. For example, the
|
|
implementation <em title="must" class="rfc2119">must</em> ensure that another transaction does not modify the contents of
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>s in the READ_WRITE transaction's <a class="internalDFN" href="#dfn-scope">scope</a>. The implementation
|
|
<em title="must" class="rfc2119">must</em> also ensure that if the READ_WRITE transaction completes successfully, the
|
|
changes written to <a class="internalDFN" href="#dfn-object-store">object store</a>s using the transaction can be committed to the
|
|
<a class="internalDFN" href="#dfn-database">database</a> without merge conflicts. An implementation <em title="must not" class="rfc2119">must not</em> abort a transaction
|
|
due to merge conflicts.
|
|
</p>
|
|
<p>
|
|
If multiple READ_WRITE transactions are attempting to access the same object store (i.e.
|
|
if they have overlapping <a class="internalDFN" href="#dfn-scope">scope</a>), the transaction that was <a class="internalDFN" href="#dfn-transaction-create" title="transaction create">
|
|
created</a> first <em title="must" class="rfc2119">must</em> be the transaction which gets access to the object store first. Due to
|
|
the requirements in the previous paragraph, this also means that it is the only transaction
|
|
which has access to the object store until the transaction is <a title="transaction finish">finished</a>.
|
|
</p>
|
|
<p class="note">
|
|
Generally speaking, the above requirements mean that READ_WRITE transactions which have overlapping
|
|
scopes always run in the order they were <a class="internalDFN" href="#dfn-transaction-create" title="transaction create">created</a>, and never run
|
|
in parallel.
|
|
</p>
|
|
<p>
|
|
User agents <em title="must" class="rfc2119">must</em> ensure a reasonable level of fairness across transactions to prevent
|
|
starvation. For example, if multiple READ_ONLY transactions are started one after another
|
|
the implementation <em title="must not" class="rfc2119">must not</em> indefinitely prevent a pending READ_WRITE
|
|
transaction from <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">starting</a>.
|
|
</p>
|
|
<p>
|
|
Each <a class="internalDFN" href="#dfn-transaction">transaction</a> object implements either the <a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a> or the
|
|
<a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a> interface.
|
|
</p>
|
|
</div> <!-- IDBTransaction -->
|
|
|
|
<div class="section" id="request-concept">
|
|
<h4><span class="secno">3.1.8 </span>Requests</h4>
|
|
<p>
|
|
Each reading and writing operation on a <a class="internalDFN" href="#dfn-database">database</a> is done using a <dfn id="dfn-request">request</dfn>.
|
|
Every request represents one read or write operation.
|
|
<a class="internalDFN" href="#dfn-request">Request</a>s have a <dfn id="dfn-request-done" title="request done"><var>done</var></dfn> flag which
|
|
initially is false, and a <dfn id="dfn-request-source" title="request source">source</dfn> object. Every request
|
|
also has a <dfn id="dfn-request-result" title="request result">result</dfn> and an <dfn id="dfn-error-attribute" title="error attribute">error attribute</dfn>,
|
|
neither of which are accessible until the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is set to true.
|
|
</p>
|
|
<p>
|
|
Finally, requests have a <dfn id="dfn-request-transaction">request transaction</dfn>. When a request is created, it is
|
|
always <dfn id="dfn-place-request" title="place request">placed</dfn> against a <a class="internalDFN" href="#dfn-transaction">transaction</a> using either the
|
|
<a href="#steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> or the
|
|
<a href="#steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>.
|
|
The steps set the <a class="internalDFN" href="#dfn-request-transaction">request transaction</a> to be that <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
The steps do not set the <a class="internalDFN" href="#dfn-request-transaction">request transaction</a> to be that request for the request returned from an
|
|
<a href="#widl-IDBFactory-open-IDBOpenDBRequest-DOMString-name-unsigned-long-long-version">IDBFactory.open</a> call however.
|
|
That function create requests which have a null <a class="internalDFN" href="#dfn-request-transaction">request transaction</a>.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="section" id="range-concept">
|
|
<h4><span class="secno">3.1.9 </span>Key Range</h4>
|
|
<p>
|
|
Records can be retrieved from <a class="internalDFN" href="#dfn-object-store">object store</a>s and <a class="internalDFN" href="#dfn-index">index</a>es
|
|
using either <a class="internalDFN" href="#dfn-key-1" title="key">keys</a> or <a class="internalDFN" href="#dfn-key-range" title="key range">key ranges</a>. A
|
|
<dfn id="dfn-key-range">key range</dfn> is a continuous interval over some data type
|
|
used for keys.
|
|
</p>
|
|
<p>
|
|
A <a class="internalDFN" href="#dfn-key-range">key range</a> <em title="may" class="rfc2119">may</em> be lower-bounded or upper-bounded
|
|
(there is a value that is, respectively, smaller than or larger than all its elements).
|
|
A <a class="internalDFN" href="#dfn-key-range">key range</a> is said to be bounded if it is both lower-bounded and upper-bounded.
|
|
If a key range is neither lower-bounded nor upper-bounded it is said to be unbounded.
|
|
A <a class="internalDFN" href="#dfn-key-range">key range</a> <em title="may" class="rfc2119">may</em> be open (the key range does not include its endpoints)
|
|
or closed (the key range includes its endpoints).
|
|
A key range <em title="may" class="rfc2119">may</em> consist of a single value.
|
|
</p>
|
|
<p>
|
|
The <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> interface defines a
|
|
<a class="internalDFN" href="#dfn-key-range">key range</a>.
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBKeyRange">interface <span class="idlInterfaceID">IDBKeyRange</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBKeyRange-lower">lower</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBKeyRange-upper">upper</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBKeyRange-upperOpen">upperOpen</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>static IDBKeyRange</a></span> <span class="idlMethName"><a href="#widl-IDBKeyRange-only-static-IDBKeyRange-any-value">only</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>static IDBKeyRange</a></span> <span class="idlMethName"><a href="#widl-IDBKeyRange-lowerBound-static-IDBKeyRange-any-bound-boolean-open">lowerBound</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">bound</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">open</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>static IDBKeyRange</a></span> <span class="idlMethName"><a href="#widl-IDBKeyRange-upperBound-static-IDBKeyRange-any-bound-boolean-open">upperBound</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">bound</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">open</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>static IDBKeyRange</a></span> <span class="idlMethName"><a href="#widl-IDBKeyRange-bound-static-IDBKeyRange-any-lower-any-upper-boolean-lowerOpen-boolean-upperOpen">bound</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">lower</span></span>, <span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">upper</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">lowerOpen</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">upperOpen</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes">Attributes</h5><dl class="attributes"><dt id="widl-IDBKeyRange-lower"><code>lower</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>This value is the lower-bound of the <a class="internalDFN" href="#dfn-key-range">key range</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBKeyRange-lowerOpen"><code>lowerOpen</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>Returns false if the lower-bound value is included in the <a class="internalDFN" href="#dfn-key-range">key range</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBKeyRange-upper"><code>upper</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>This value is the upper-bound of the <a class="internalDFN" href="#dfn-key-range">key range</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBKeyRange-upperOpen"><code>upperOpen</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>Returns false if the upper-bound value is included in the <a class="internalDFN" href="#dfn-key-range">key range</a>.<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods">Methods</h5><dl class="methods"><dt id="widl-IDBKeyRange-bound-static-IDBKeyRange-any-lower-any-upper-boolean-lowerOpen-boolean-upperOpen"><code>bound</code></dt><dd>
|
|
Creates and returns a new <a class="internalDFN" href="#dfn-key-range">key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
|
|
<var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to <var>lowerOpen</var>,
|
|
<a href="#widl-IDBKeyRange-upper">upper</a> set to <var>upper</var> and
|
|
<a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>upperOpen</var>.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">lower</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The lower-bound value</td></tr><tr><td class="prmName">upper</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The upper-bound value</td></tr><tr><td class="prmName">lowerOpen</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Is the lower-bound value included in the <a class="internalDFN" href="#dfn-key-range">key range</a>. Defaults to false.</td></tr><tr><td class="prmName">upperOpen</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Is the upper-bound value included in the <a class="internalDFN" href="#dfn-key-range">key range</a>. Defaults to false.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">Either the <var>lower</var> or <var>upper</var> parameters were not passed a <a class="internalDFN" href="#dfn-valid-key">valid key</a>
|
|
or the lower key is greater than the upper key or the lower key and upper key match and either
|
|
of the bounds are open.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>static IDBKeyRange</a></code></div></dd><dt id="widl-IDBKeyRange-lowerBound-static-IDBKeyRange-any-bound-boolean-open"><code>lowerBound</code></dt><dd>
|
|
Creates and returns a new <a class="internalDFN" href="#dfn-key-range">key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
|
|
<var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to <var>open</var>,
|
|
<a href="#widl-IDBKeyRange-upper">upper</a> set to <code>undefined</code> and
|
|
and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to true.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">bound</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The lower bound value</td></tr><tr><td class="prmName">open</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Is the lower-bound value included in the <a class="internalDFN" href="#dfn-key-range">key range</a>. Defaults to false.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>value</var> parameter was not passed a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>static IDBKeyRange</a></code></div></dd><dt id="widl-IDBKeyRange-only-static-IDBKeyRange-any-value"><code>only</code></dt><dd>
|
|
Creates and returns a new <a class="internalDFN" href="#dfn-key-range">key range</a> with both <a href="#widl-IDBKeyRange-lower">lower</a> and
|
|
<a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and both
|
|
<a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a>
|
|
set to false.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The only value</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>value</var> parameter was not passed a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>static IDBKeyRange</a></code></div></dd><dt id="widl-IDBKeyRange-upperBound-static-IDBKeyRange-any-bound-boolean-open"><code>upperBound</code></dt><dd>
|
|
Creates and returns a new <a class="internalDFN" href="#dfn-key-range">key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
|
|
<code>undefined</code>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to true,
|
|
<a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and
|
|
and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>open</var>.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">bound</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The upper bound value</td></tr><tr><td class="prmName">open</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Is the upper-bound value included in the <a class="internalDFN" href="#dfn-key-range">key range</a>. Defaults to false.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>value</var> parameter was not passed a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>static IDBKeyRange</a></code></div></dd></dl></div>
|
|
<p>
|
|
A <a class="internalDFN" href="#dfn-key-1"><var>key</var></a> is <dfn id="dfn-in-a-key-range">in a <a class="internalDFN" href="#dfn-key-range">key range</a></dfn> if both the following conditions are
|
|
fulfilled:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The <a class="internalDFN" href="#dfn-key-range">key range</a> <a href="#widl-IDBKeyRange-lower"><code>lower</code></a> value is <code>undefined</code> or
|
|
<a class="internalDFN" href="#dfn-less-than">less than</a> <var>key</var>. It may also be <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var> if
|
|
<a href="#widl-IDBKeyRange-lowerOpen"><code>lowerOpen</code></a> is <code>false</code>.
|
|
</li>
|
|
<li>
|
|
The <a class="internalDFN" href="#dfn-key-range">key range</a> <a href="#widl-IDBKeyRange-upper"><code>upper</code></a> value is <code>undefined</code> or
|
|
<a class="internalDFN" href="#dfn-greater-than">greater than</a> <var>key</var>. It may also be <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var> if
|
|
<a href="#widl-IDBKeyRange-upperOpen"><code>upperOpen</code></a> is <code>false</code>.
|
|
</li>
|
|
</ul>
|
|
</div> <!-- Key Range -->
|
|
|
|
<div id="cursor-concept" class="section">
|
|
<h4><span class="secno">3.1.10 </span>Cursor</h4>
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-cursor" title="cursor">Cursors</a> are a transient mechanism used to
|
|
iterate over multiple records in a database.
|
|
Storage operations are performed on the underlying <a class="internalDFN" href="#dfn-index">index</a> or an
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
<p>
|
|
A <dfn id="dfn-cursor">cursor</dfn> comprises a <dfn id="dfn-range">range</dfn> of records in either an <a class="internalDFN" href="#dfn-index">index</a>
|
|
or an <a class="internalDFN" href="#dfn-object-store">object store</a>. The cursor has a <dfn id="dfn-cursor-source" title="cursor source">source</dfn> that indicates
|
|
which index or object store is associated with the records over which the <a class="internalDFN" href="#dfn-cursor">cursor</a> is iterating.
|
|
A <a class="internalDFN" href="#dfn-cursor">cursor</a> maintains a <dfn id="dfn-position">position</dfn> over
|
|
this series, which moves in a <dfn id="dfn-direction">direction</dfn> that is in either
|
|
monotonically increasing or decreasing order of the <a class="internalDFN" href="#dfn-record">record</a> keys. Cursors
|
|
also have a <dfn id="dfn-cursor-key" title="cursor key">key</dfn> and a <dfn id="dfn-cursor-value" title="cursor value">value</dfn>
|
|
which represent the <a class="internalDFN" href="#dfn-key-1">key</a> and the <a class="internalDFN" href="#dfn-value-1">value</a> of the last iterated <a class="internalDFN" href="#dfn-record">record</a>.
|
|
Cursors finally have a <dfn id="dfn-got-value">got value</dfn> flag. When this flag is false, the cursor is either
|
|
in the process of loading the next value or it has reached the end of its <a class="internalDFN" href="#dfn-range">range</a>, when it
|
|
is true, it indicates that the cursor is currently holding a value and that it is ready to iterate
|
|
to the next one.
|
|
</p>
|
|
<p>
|
|
If the <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> of a cursor is an <a class="internalDFN" href="#dfn-object-store">object store</a>, the <dfn id="dfn-effective-object-store">effective object store</dfn>
|
|
of the cursor is that object store and the <dfn id="dfn-effective-key">effective key</dfn> of the cursor is the cursor's <a class="internalDFN" href="#dfn-position">position</a>.
|
|
If the <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> of a cursor is an <a class="internalDFN" href="#dfn-index">index</a>, the <a class="internalDFN" href="#dfn-effective-object-store">effective object store</a>
|
|
of the cursor is that index's <a class="internalDFN" href="#dfn-referenced">referenced</a> object store and the <a class="internalDFN" href="#dfn-effective-key">effective key</a> is the cursor's
|
|
<a class="internalDFN" href="#dfn-object-store-position">object store position</a>.
|
|
</p>
|
|
<p>
|
|
It is possible for the list of records which the cursor is iterating over to
|
|
change before the full <a class="internalDFN" href="#dfn-range">range</a> of the cursor has been iterated. In order to
|
|
handle this, cursors maintain their <a class="internalDFN" href="#dfn-position">position</a> not as an index, but rather
|
|
as a <a class="internalDFN" href="#dfn-key-1">key</a> of the previously returned record. For a forward iterating cursor,
|
|
the next time the cursor is asked to iterate to the next record it returns the
|
|
record with the lowest <a class="internalDFN" href="#dfn-key-1">key</a> <a class="internalDFN" href="#dfn-greater-than">greater than</a> the one previously returned. For
|
|
a backwards iterating cursor, the situation is opposite and it returns the record
|
|
with the highest <a class="internalDFN" href="#dfn-key-1">key</a> <a class="internalDFN" href="#dfn-less-than">less than</a> the one previously returned.
|
|
</p>
|
|
<p>
|
|
For cursors iterating indexes the situation is a little bit more complicated since
|
|
multiple records can have the same key and are therefore also sorted by <a class="internalDFN" href="#dfn-value-1">value</a>.
|
|
When iterating indexes the <a class="internalDFN" href="#dfn-cursor">cursor</a> also has an <dfn id="dfn-object-store-position">object store position</dfn>, which indicates
|
|
the <a class="internalDFN" href="#dfn-value-1">value</a> of the previously found <a class="internalDFN" href="#dfn-record">record</a> in the index. Both
|
|
<a class="internalDFN" href="#dfn-position">position</a> and the <a class="internalDFN" href="#dfn-object-store-position">object store position</a> are used when finding the next appropriate record.
|
|
</p>
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-cursor" title="cursor">Cursor</a> objects implement the <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a>
|
|
or the <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> interfaces. There is only ever one
|
|
<a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> or <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> instance representing
|
|
a given <a class="internalDFN" href="#dfn-cursor">cursor</a>. However there is no limit on how many cursors can be used at the
|
|
same time.
|
|
</p>
|
|
</div> <!-- IDBCursor -->
|
|
<div id="exceptions" class="section">
|
|
<h4><span class="secno">3.1.11 </span>Exceptions</h4>
|
|
<p>
|
|
Each of the exceptions defined in the IndexedDB spec is a <code><dfn id="dfn-domexception">DOMException</dfn></code> with a specific type. [<cite><a href="#bib-DOM4" rel="biblioentry" class="bibref">DOM4</a></cite>]
|
|
|
|
Existing DOM Level 4 exceptions will set their code to a
|
|
legacy value; however, the new indexedDB type exceptions will have a
|
|
code value of 0.
|
|
The message value is optional.
|
|
</p>
|
|
<p>
|
|
IndexedDB uses the following new <code>DOMException</code> types with their various messages.
|
|
All of these new types will have a code value of <code>0</code> zero.
|
|
</p>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Type</th>
|
|
<th>Message (Optional)</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-unknownerror">UnknownError</dfn></code></td>
|
|
<td>The operation failed for reasons unrelated to the database itself and not covered by any other errors.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-constrainterror">ConstraintError</dfn></code></td>
|
|
<td>
|
|
A mutation operation in the transaction failed because a constraint was not satisfied.
|
|
For example, an object such as an <a class="internalDFN" href="#dfn-object-store">object store</a> or <a class="internalDFN" href="#dfn-index">index</a> already exists and a request attempted to create a new one.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-dataerror">DataError</dfn></code></td>
|
|
<td>Data provided to an operation does not meet requirements.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-transactioninactiveerror">TransactionInactiveError</dfn></code></td>
|
|
<td>A request was placed against a transaction which is currently not active, or which is finished.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-readonlyerror">ReadOnlyError</dfn></code></td>
|
|
<td>The mutating operation was attempted in a READ_ONLY transaction.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-versionerror">VersionError</dfn></code></td>
|
|
<td>An attempt was made to open a database using a lower version than the existing version.</td>
|
|
</tr>
|
|
</tbody></table>
|
|
<p>
|
|
IndexedDB reuses the following existing <a class="internalDFN" href="#dfn-domexception">DOMException</a> types from [<cite><a href="#bib-DOM4" rel="biblioentry" class="bibref">DOM4</a></cite>].
|
|
These types will continue to return the codes and names as specified in DOM4;
|
|
however, they will have the following messages when thrown from an IndexedDB API:
|
|
</p>
|
|
<table>
|
|
<tbody><tr>
|
|
<th>Type</th>
|
|
<th>Message (Optional)</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-notfounderror">NotFoundError</dfn></code></td>
|
|
<td>
|
|
The operation failed because the requested database object could not be found.
|
|
For example, an <a class="internalDFN" href="#dfn-object-store">object store</a> did not exist but was being opened.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-invalidstateerror">InvalidStateError</dfn></code></td>
|
|
<td>
|
|
An operation was called on an object on which it is not allowed or at a time when it is not allowed.
|
|
Also occurs if a request is made on a source object that has been deleted or removed.
|
|
Use <a class="internalDFN" href="#dfn-transactioninactiveerror">TransactionInactiveError</a> or <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> when possible, as they are more specific variations of <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-invalidaccesserror">InvalidAccessError</dfn></code></td>
|
|
<td>
|
|
An invalid operation was performed on an object. For example transaction creation attempt was made,
|
|
but an empty scope was provided.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-aborterror">AbortError</dfn></code></td>
|
|
<td>
|
|
A <a class="internalDFN" href="#dfn-request">request</a> was aborted, for example through a call to <code>IDBTransaction.abort</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-timeouterror">TimeoutError</dfn></code></td>
|
|
<td>A lock for the <a class="internalDFN" href="#dfn-transaction">transaction</a> could not be obtained in a reasonable time.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-quotaexceedederror">QuotaExceededError</dfn></code></td>
|
|
<td>
|
|
The operation failed because there was not enough remaining storage space,
|
|
or the storage quota was reached and the user declined to give more space to the database.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-syntaxerror">SyntaxError</dfn></code></td>
|
|
<td>The <code>keypath</code> argument contains an invalid <a class="internalDFN" href="#dfn-key-path">key path</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><dfn id="dfn-datacloneerror">DataCloneError</dfn></code></td>
|
|
<td>The data being stored could not be cloned by the internal structured cloning algorithm.</td>
|
|
</tr>
|
|
</tbody></table>
|
|
|
|
</div>
|
|
<div id="options-object-concept" class="section">
|
|
<h4><span class="secno">3.1.12 </span>Options Object</h4>
|
|
<p>
|
|
<dfn id="dfn-options-object">Options object</dfn>s are dictionary objects [<cite><a href="#bib-WEBIDL" rel="biblioentry" class="bibref">WEBIDL</a></cite>]
|
|
which are used to supply optional parameters to some indexedDB functions like
|
|
<a href="#widl-IDBDatabase-createObjectStore-IDBObjectStore-DOMString-name-IDBObjectStoreParameters-optionalParameters">createObjectStore</a> and
|
|
<a href="#widl-IDBObjectStore-createIndex-IDBIndex-DOMString-name-DOMString-keyPath-IDBIndexParameters-optionalParameters">createIndex</a>. The attributes on the object
|
|
correspond to optional parameters on the function called.
|
|
</p>
|
|
<div class="block">
|
|
<div class="blockTitleDiv"><span class="blockTitle">IDL</span></div>
|
|
<div class="blockContent">
|
|
<p>The following WebIDL defines <dfn id="dfn-idbobjectstoreparameters">IDBObjectStoreParameters</dfn> dictionary type.</p>
|
|
<pre class="code"> <code class="es-code">
|
|
dictionary IDBObjectStoreParameters {
|
|
DOMString? keyPath = null;
|
|
boolean autoIncrement = false;
|
|
};
|
|
</code>
|
|
</pre>
|
|
<p>The following WebIDL defines <dfn id="dfn-idbindexparameters">IDBIndexParameters</dfn> dictionary type.</p>
|
|
<pre class="code"> <code class="es-code">
|
|
dictionary IDBIndexParameters {
|
|
boolean unique = false;
|
|
boolean multientry = false;
|
|
};
|
|
</code>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div> <!-- Options Object -->
|
|
</div>
|
|
<div class="section" id="async-api">
|
|
<h3><span class="secno">3.2 </span>Asynchronous APIs</h3>
|
|
<p>
|
|
The asynchronous API methods return without blocking the calling thread.
|
|
All asynchronous operations immediately return an <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> instance.
|
|
This object does not initially contain any information about the result of the operation.
|
|
Once information becomes available, an event is fired on the request and the information becomes
|
|
available through the properties of the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> instance.
|
|
</p>
|
|
|
|
<div class="section" id="request-api">
|
|
<h4><span class="secno">3.2.1 </span>The <code>IDBRequest</code> Interface</h4>
|
|
<p>
|
|
The <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> interface provides means to access results of
|
|
asynchronous requests to <a class="internalDFN" href="#dfn-database" title="database">databases</a> and <a class="internalDFN" href="#dfn-database">database</a>
|
|
<a>objects</a> using <a class="internalDFN" href="#event-handler-attributes">event handler attributes</a> [<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>].
|
|
</p>
|
|
<div class="example"><div class="exampleHeader">Example</div>
|
|
<p>
|
|
In the following example, we open a <a class="internalDFN" href="#dfn-database">database</a> asynchronously. Various
|
|
event handlers are registered for responding to various situations.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">
|
|
var request = indexedDB.<a>open</a>('AddressBook', 'Address Book');
|
|
request.<a>onsuccess</a> = function(evt) {...};
|
|
request.<a>onerror</a> = function(evt) {...};
|
|
</code></pre></div></div>
|
|
</div>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBRequest">interface <span class="idlInterfaceID">IDBRequest</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBRequest-LOADING">LOADING</a></span> = <span class="idlConstValue">1</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBRequest-DONE">DONE</a></span> = <span class="idlConstValue">2</span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBRequest-result">result</a></span> getraises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMError</a></span> <span class="idlAttrName"><a href="#widl-IDBRequest-error">error</a></span> getraises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Object</a></span> <span class="idlAttrName"><a href="#widl-IDBRequest-source">source</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></span> <span class="idlAttrName"><a href="#widl-IDBRequest-transaction">transaction</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-IDBRequest-readyState">readyState</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBRequest-onsuccess">onsuccess</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBRequest-onerror">onerror</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-1">Attributes</h5><dl class="attributes"><dt id="widl-IDBRequest-error"><code>error</code> of type <span class="idlAttrType"><a>DOMError</a></span>, readonly</dt><dd>
|
|
When the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is true, getting this
|
|
property <em title="must" class="rfc2119">must</em> return the error of
|
|
the request. This is null when no error occurred. When the
|
|
<a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is false, getting this property
|
|
<em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
<!-- XXX The js-library doesn't do the exception correctly here -->
|
|
|
|
<table class="exceptions"><tr><th>Exception</th><th>On Get</th><th>On Set</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excGetSetTrue">✔</td><td class="excGetSetFalse">✘</td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Thrown when this attribute was read when the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag was set to false.</td></tr></table></td></tr></table></dd><dt id="widl-IDBRequest-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a title="event-error">error event</a><div><em>No exceptions.</em></div></dd><dt id="widl-IDBRequest-onsuccess"><code>onsuccess</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a title="event-success">success event</a><div><em>No exceptions.</em></div></dd><dt id="widl-IDBRequest-readyState"><code>readyState</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>When the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is false, returns
|
|
<a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a>,
|
|
otherwise returns
|
|
<a class="idlType" href="#widl-IDBRequest-DONE"><code>DONE</code></a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBRequest-result"><code>result</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>
|
|
When the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is true, getting this
|
|
property <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-request-result" title="request result">result</a> of
|
|
the request. This is <code>undefined</code> when the request resulted
|
|
in an error. When the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag is
|
|
false, getting this property <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror"><code>InvalidStateError</code></a>.
|
|
|
|
<table class="exceptions"><tr><th>Exception</th><th>On Get</th><th>On Set</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excGetSetTrue">✔</td><td class="excGetSetFalse">✘</td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Thrown when this attribute was read when the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag was set to false.</td></tr></table></td></tr></table></dd><dt id="widl-IDBRequest-source"><code>source</code> of type <span class="idlAttrType"><a>Object</a></span>, readonly</dt><dd>
|
|
Getting this property <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-request-source" title="request source">source</a>
|
|
for the request. Returns <code>null</code> when there is no <a class="internalDFN" href="#dfn-request-source" title="request source">source</a> set.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBRequest-transaction"><code>transaction</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></span>, readonly</dt><dd>
|
|
Getting this property <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-request-transaction" title="request transaction">transaction</a>
|
|
for the request. This property can be null for certain requests, such as for <a class="internalDFN" href="#dfn-request">request</a>
|
|
returned from <a href="#widl-IDBFactory-open-IDBOpenDBRequest-DOMString-name-unsigned-long-long-version">IDBFactory.open</a>.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="constants">Constants</h5><dl class="constants"><dt id="widl-IDBRequest-DONE"><code>DONE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>This state indicates that a result to a previous request is available in
|
|
the <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> attribute.</dd><dt id="widl-IDBRequest-LOADING"><code>LOADING</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>This state indicates that a request has been started but its results is not
|
|
yet available.</dd></dl></div>
|
|
<p>
|
|
When a request is made, a new <a class="internalDFN" href="#dfn-request">request</a> is returned with its
|
|
<a class="idlType" href="#widl-IDBRequest-readyState"><code>readyState</code></a> set to
|
|
<a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a>.
|
|
If a request completes successfully, the
|
|
<a class="idlType" href="#widl-IDBRequest-readyState"><code>readyState</code></a>
|
|
is changed to <a class="idlType" href="#widl-IDBRequest-DONE"><code>DONE</code></a>, the
|
|
<a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a>
|
|
is set to the result of the request, and an event with type <code>success</code> is fired
|
|
at the <a class="internalDFN" href="#dfn-request">request</a>.
|
|
</p>
|
|
<p>
|
|
If an error occurs while performing the operation, the
|
|
<a class="idlType" href="#widl-IDBRequest-readyState"><code>readyState</code></a>
|
|
is changed to <a class="idlType" href="#widl-IDBRequest-DONE"><code>DONE</code></a>, the
|
|
<code>error</code> attribute is set to a <code>DOMError</code> type that matches the error,
|
|
and an event with type <code>error</code> is fired at the request.
|
|
</p>
|
|
<p>
|
|
The <code>open</code> function on <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a>
|
|
uses a separate interface for its <a class="internalDFN" href="#dfn-request">request</a>s in order to make use of the
|
|
<code>blocked event</code> and <code>upgradeneeded event</code> easier.
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBOpenDBRequest">interface <span class="idlInterfaceID">IDBOpenDBRequest</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> {
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBOpenDBRequest-onblocked">onblocked</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBOpenDBRequest-onupgradeneeded">onupgradeneeded</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-2">Attributes</h5><dl class="attributes"><dt id="widl-IDBOpenDBRequest-onblocked"><code>onblocked</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <code>blocked event</code><div><em>No exceptions.</em></div></dd><dt id="widl-IDBOpenDBRequest-onupgradeneeded"><code>onupgradeneeded</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <code>upgradeneeded event</code><div><em>No exceptions.</em></div></dd></dl></div>
|
|
<p>
|
|
The <span>task source</span> for these tasks is the
|
|
<dfn id="database-access-task-source">database access task source</dfn>.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="section" id="events">
|
|
<h4><span class="secno">3.2.2 </span>Event interfaces</h4>
|
|
<p>
|
|
This specification fires events with the following custom interfaces:
|
|
</p>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBVersionChangeEvent">interface <span class="idlInterfaceID">IDBVersionChangeEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-IDBVersionChangeEvent-oldVersion">oldVersion</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-IDBVersionChangeEvent-newVersion">newVersion</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBVersionChangeEvent-initIDBVersionChangeEvent-void-DOMString-typeArg-boolean-canBubbleArg-boolean-cancelableArg-unsigned-long-long-oldVersion-unsigned-long-long-newVersion">initIDBVersionChangeEvent</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">typeArg</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">canBubbleArg</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">cancelableArg</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">oldVersion</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">newVersion</span></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-3">Attributes</h5><dl class="attributes"><dt id="widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>Returns the new version of the database.
|
|
See the <a class="internalDFN" href="#dfn-steps-for-running-a-version_change-transaction">steps for running a <code>VERSION_CHANGE</code> transaction</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>Returns the old version of the database.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-1">Methods</h5><dl class="methods"><dt id="widl-IDBVersionChangeEvent-initIDBVersionChangeEvent-void-DOMString-typeArg-boolean-canBubbleArg-boolean-cancelableArg-unsigned-long-long-oldVersion-unsigned-long-long-newVersion"><code>initIDBVersionChangeEvent</code></dt><dd>
|
|
<p>Intializes the value of an <a href="#idl-def-IDBVersionChangeEvent">IDBVersionChangeEvent</a> event once it's been created.</p>
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">typeArg</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Specifies the event type.</td></tr><tr><td class="prmName">canBubbleArg</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Boolean value that indicates whether the event can bubble.</td></tr><tr><td class="prmName">cancelableArg</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Boolean value that indicates whether the event is cancelable.</td></tr><tr><td class="prmName">oldVersion</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The old version of the database during a VERSION_CHANGE transaction.</td></tr><tr><td class="prmName">newVersion</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The new version of the database during a VERSION_CHANGE transaction.</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
|
|
|
|
</div>
|
|
|
|
<div class="section" id="requests">
|
|
<h4><span class="secno">3.2.3 </span>Opening a database</h4>
|
|
<p>
|
|
<a title="Window" class="externalDFN"><code>Window</code></a> and
|
|
<a title="WorkerUtils" class="externalDFN"><code>WorkerUtils</code></a> objects
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a> interface.
|
|
</p>
|
|
<pre class="idl"><span class="idlImplements"><a>Window</a> implements <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Window</a></code> type are defined to also implement the <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a> interface.</p></div>
|
|
<pre class="idl"><span class="idlImplements"><a>WorkerUtils</a> implements <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>WorkerUtils</a></code> type are defined to also implement the <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a> interface.</p></div>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBEnvironment">[<span class="extAttr">NoInterfaceObject</span>]
|
|
interface <span class="idlInterfaceID">IDBEnvironment</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBFactory"><code>IDBFactory</code></a></span> <span class="idlAttrName"><a href="#widl-IDBEnvironment-indexedDB">indexedDB</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-4">Attributes</h5><dl class="attributes"><dt id="widl-IDBEnvironment-indexedDB"><code>indexedDB</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBFactory"><code>IDBFactory</code></a></span>, readonly</dt><dd>This attribute provides applications a mechanism for accessing
|
|
capabilities of indexed databases.<div><em>No exceptions.</em></div></dd></dl></div>
|
|
<p>
|
|
Every method for making asynchronous requests returns an
|
|
<a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> object that communicates back to the requesting
|
|
application through events.
|
|
This design means that any number of requests can be active on any <a class="internalDFN" href="#dfn-database">database</a>
|
|
or <a title="objects">object</a> handle at a time.
|
|
</p>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBFactory">interface <span class="idlInterfaceID">IDBFactory</span> {
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBFactory-open-IDBOpenDBRequest-DOMString-name-unsigned-long-long-version">open</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam">[<span class="extAttr">EnforceRange</span>] optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">version</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBFactory-deleteDatabase-IDBOpenDBRequest-DOMString-name">deleteDatabase</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>short</a></span> <span class="idlMethName"><a href="#widl-IDBFactory-cmp-short-any-first-any-second">cmp</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">first</span></span>, <span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">second</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="methods-2">Methods</h5><dl class="methods"><dt id="widl-IDBFactory-cmp-short-any-first-any-second"><code>cmp</code></dt><dd>
|
|
<p>
|
|
When invoked, this method <em title="must" class="rfc2119">must</em> compare two <a class="internalDFN" href="#dfn-key-1">key</a>s. The method returns 1 if the first key is
|
|
<a class="internalDFN" href="#dfn-greater-than">greater than</a> the second, -1 if the first is <a class="internalDFN" href="#dfn-less-than">less than</a> the second, and 0 if
|
|
the first is <a class="internalDFN" href="#dfn-equal-to">equal to</a> the second.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">first</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The first <a class="internalDFN" href="#dfn-key-1">key</a> to compare.</td></tr><tr><td class="prmName">second</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The second <a class="internalDFN" href="#dfn-key-1">key</a> to compare.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">One of the supplied keys was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>short</a></code></div></dd><dt id="widl-IDBFactory-deleteDatabase-IDBOpenDBRequest-DOMString-name"><code>deleteDatabase</code></dt><dd>
|
|
<p>
|
|
When invoked, this method <em title="must" class="rfc2119">must</em> create a <a class="internalDFN" href="#dfn-request">request</a> and return it. The created
|
|
<a class="internalDFN" href="#dfn-request">request</a> has no <a class="internalDFN" href="#dfn-request-source" title="request source">source</a>.
|
|
The method then queues up an operation to run the <a class="internalDFN" href="#dfn-steps-for-deleting-a-database">steps for deleting a database</a>.
|
|
Let <var>origin</var> be the origin of the <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a> used to access
|
|
this <a class="idlType" href="#idl-def-IDBFactory"><code>IDBFactory</code></a> and <var>name</var> be the <var>name</var> parameter passed
|
|
to this function.
|
|
</p>
|
|
<p>
|
|
If an error is returned from the steps above, the implementation <em title="must" class="rfc2119">must</em>
|
|
set the <code>error</code> attribute to a <code>DOMError</code> with the same type of error returned
|
|
and <a class="internalDFN" href="#dfn-fire-an-error-event">fire an error event</a> at the <a class="internalDFN" href="#dfn-request">request</a>.
|
|
</p>
|
|
<p>
|
|
If the steps above are successful, the implementation <em title="must" class="rfc2119">must</em> set the
|
|
<a class="internalDFN" href="#dfn-request-result" title="request result">result</a> of the <var>request</var>
|
|
to <code>null</code> and <a class="internalDFN" href="#dfn-fire-a-success-event">fire a success event</a> at
|
|
the <a class="internalDFN" href="#dfn-request">request</a>.
|
|
The request will be an <a>IDBVersionChangeRequest</a> returned by those steps.
|
|
</p>
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-database-name" title="database name">name</a> for the <a class="internalDFN" href="#dfn-database">database</a></td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a></code></div></dd><dt id="widl-IDBFactory-open-IDBOpenDBRequest-DOMString-name-unsigned-long-long-version"><code>open</code></dt><dd>
|
|
<p>
|
|
When invoked, this method <em title="must" class="rfc2119">must</em> create a <a class="internalDFN" href="#dfn-request">request</a> and return it. The created
|
|
<a class="internalDFN" href="#dfn-request">request</a> <em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a> interface and have its
|
|
<a class="internalDFN" href="#dfn-request-source" title="request source">source</a> set to <code>null</code>.
|
|
The method then queues up an operation to run the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>.
|
|
Let <var>origin</var> be the origin of the <a class="idlType" href="#idl-def-IDBEnvironment"><code>IDBEnvironment</code></a> used to access
|
|
this <a class="idlType" href="#idl-def-IDBFactory"><code>IDBFactory</code></a>, <var>name</var> and <var>version</var> be the <var>name</var>
|
|
and <var>version</var> parameters passed to this function, and <var>request</var> be
|
|
the newly created request.
|
|
</p>
|
|
<p>
|
|
If no version is specified and a database exists,
|
|
use the current database version and follow the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>.
|
|
If no version is specified and no database exists,
|
|
set database version to 1, follow the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>,
|
|
and return a database without <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a>.
|
|
</p>
|
|
<p>
|
|
If an error is returned from the steps above, the implementation <em title="must" class="rfc2119">must</em> set the
|
|
<code>error</code> attribute of the <var>request</var>
|
|
to a <code>DOMError</code> whose type is the same as the error returned,
|
|
of the <var>request</var> to null, and dispatch an event at <var>request</var>.
|
|
The event must use the <code>Event</code> interface and have its <code>type</code> set
|
|
to <code>"error"</code>. The event does bubble but is not cancelable. The <a class="internalDFN" href="#dfn-propagation-path">propagation
|
|
path</a> of the event is just the request.
|
|
</p>
|
|
<p>
|
|
If the steps above are successful, the implementation <em title="must" class="rfc2119">must</em> set the
|
|
<code>error</code> attribute of the request to a <code>DOMError</code> whose type is the same as the error returned,
|
|
to the <a class="internalDFN" href="#dfn-connection">connection</a> created by the steps above and dispatch an event at <var>request</var>.
|
|
The event must use the <code>Event</code> interface and have its <code>type</code> set
|
|
to <code>"success"</code>. The event does not bubble and is not cancelable. The <a class="internalDFN" href="#dfn-propagation-path">propagation
|
|
path</a> of the event is just the request. If the steps above resulted in a VERSION_CHANGE transaction being
|
|
run, then firing the <code>"success"</code> event <em title="must" class="rfc2119">must</em> be done in the same task as was used
|
|
</p>
|
|
<p class="note">
|
|
The last requirement is to ensure that in case another version upgrade is about to happen,
|
|
the success event is fired on the connection first so that the page gets a chance to register
|
|
a listener for the <code>versionchange</code> event.
|
|
</p>
|
|
<p class="note">
|
|
The firing of <code>"success"</code> or <code>"error"</code> events do not follow the normal
|
|
steps to <a class="internalDFN" href="#dfn-fire-a-success-event">fire a success event</a> or <a class="internalDFN" href="#dfn-fire-an-error-event">fire an error event</a> as there is no active
|
|
transaction at the time when they fire.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-database-name" title="database name">name</a> for the <a class="internalDFN" href="#dfn-database">database</a></td></tr><tr><td class="prmName">version</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-version">version</a> for the <a class="internalDFN" href="#dfn-database">database</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value of <code>version</code> is <code>0</code> (zero) or a negative number.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBOpenDBRequest"><code>IDBOpenDBRequest</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
<div id="database-interface" class="section">
|
|
<h4><span class="secno">3.2.4 </span>Database</h4>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<p>
|
|
A <a class="internalDFN" href="#dfn-database">database</a> object can be used to manipulate the
|
|
<a>objects</a> of that <a class="internalDFN" href="#dfn-database">database</a>. It is also the only way to
|
|
obtain a <a class="internalDFN" href="#dfn-transaction">transaction</a> for that <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBDatabase">interface <span class="idlInterfaceID">IDBDatabase</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabase-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabase-version">version</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMStringList</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabase-objectStoreNames">objectStoreNames</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></span> <span class="idlMethName"><a href="#widl-IDBDatabase-createObjectStore-IDBObjectStore-DOMString-name-IDBObjectStoreParameters-optionalParameters">createObjectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>IDBObjectStoreParameters</a></span> <span class="idlParamName">optionalParameters</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBDatabase-deleteObjectStore-void-DOMString-name">deleteObjectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></span> <span class="idlMethName"><a href="#widl-IDBDatabase-transaction-IDBTransaction-any-storeNames-unsigned-short-mode">transaction</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">storeNames</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">mode</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBDatabase-close-void">close</a></span> ();</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBDatabase-onabort">onabort</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBDatabase-onerror">onerror</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBDatabase-onversionchange">onversionchange</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-5">Attributes</h5><dl class="attributes"><dt id="widl-IDBDatabase-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-database-name" title="database name">name</a>
|
|
of the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. The function <em title="must" class="rfc2119">must</em>
|
|
return this name even if the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>.
|
|
In other words, the return value from this function
|
|
stays constant for the lifetime of the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabase-objectStoreNames"><code>objectStoreNames</code> of type <span class="idlAttrType"><a>DOMStringList</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return a list of names of the
|
|
<a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> currently in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
Once the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>, this
|
|
function <em title="must" class="rfc2119">must</em> return a snapshot of the list of names of the <a class="internalDFN" href="#dfn-object-store">object
|
|
store</a>s taken at the time when the
|
|
<a href="#widl-IDBDatabase-close-void">close</a> method was called. Even if
|
|
other <a class="internalDFN" href="#dfn-connection">connection</a>s are later used to change the set of <a class="internalDFN" href="#dfn-object-store">object
|
|
store</a>s that exist in the <a class="internalDFN" href="#dfn-database">database</a>. In other words, the return
|
|
value from this function stays constant for the lifetime of the
|
|
<a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance, except during a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
transaction if <a href="#widl-IDBDatabase-createObjectStore-IDBObjectStore-DOMString-name-IDBObjectStoreParameters-optionalParameters">createObjectStore</a>
|
|
or <a href="#widl-IDBDatabase-deleteObjectStore-void-DOMString-name">deleteObjectStore</a>
|
|
is called on this <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance itself.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabase-onabort"><code>onabort</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>abort event</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabase-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>error event</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabase-onversionchange"><code>onversionchange</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>versionchange event</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabase-version"><code>version</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-version">version</a> of this
|
|
<a class="internalDFN" href="#dfn-database">database</a>. This attribute has value 0 when the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a> is first created.
|
|
Once the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>, this
|
|
function <em title="must" class="rfc2119">must</em> return a snapshot of the <a class="internalDFN" href="#dfn-version">version</a> taken when the
|
|
<a href="#widl-IDBDatabase-close-void">close</a> method was called. Even if
|
|
other <a class="internalDFN" href="#dfn-connection">connection</a>s are later used to change the <a class="internalDFN" href="#dfn-version">version</a> of the
|
|
<a class="internalDFN" href="#dfn-database">database</a>. In other words, the return value from this function
|
|
stays constant for the lifetime of the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-3">Methods</h5><dl class="methods"><dt id="widl-IDBDatabase-close-void"><code>close</code></dt><dd>
|
|
This method returns immediately and performs the <a class="internalDFN" href="#dfn-steps-for-closing-a-database-connection">steps for closing a database connection</a>.
|
|
<div><em>No parameters.</em></div><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBDatabase-createObjectStore-IDBObjectStore-DOMString-name-IDBObjectStoreParameters-optionalParameters"><code>createObjectStore</code></dt><dd>
|
|
<p>
|
|
This method creates and returns a new <a class="internalDFN" href="#dfn-object-store">object store</a> with the given name in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. If this function is called from
|
|
outside a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a> callback, or if this
|
|
function is called on a <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> object other than that transaction's
|
|
<a title="transaction conection">connection</a>, the implementation <em title="must" class="rfc2119">must</em> throw a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror"><code>InvalidStateError</code></a>.
|
|
</p>
|
|
<p>
|
|
If an objectStore with the same name already
|
|
exists, the implementation <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-constrainterror"><code>ConstraintError</code></a>.
|
|
Otherwise, the implementation <em title="must" class="rfc2119">must</em> create a new <a class="internalDFN" href="#dfn-object-store">object store</a> and return an <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> object representing it.
|
|
</p>
|
|
<p>
|
|
This method synchronously modifies the
|
|
<a href="#widl-IDBDatabase-objectStoreNames">IDBDatabase.objectStoreNames</a> property. However it
|
|
only changes the <a href="#widl-IDBDatabase-objectStoreNames">IDBDatabase.objectStoreNames</a>
|
|
property on the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance on which it was called.
|
|
</p>
|
|
<p>
|
|
If the <var>optionalParameters</var> argument is specified and has a <code>keyPath</code> property
|
|
which is not <code>undefined</code> or <code>null</code>, then set <var>keyPath</var> to the value
|
|
of this property. If <var>keyPath</var> is an <code>Array</code>, then each item in the array is
|
|
converted to a string. If <var>keyPath</var> is not an <code>Array</code>, it is converted to a
|
|
string.
|
|
</p>
|
|
<p>
|
|
If <var>keyPath</var> is an <code>Array</code> and any items in the array is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a>,
|
|
or if <var>keyPath</var> is a string and is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a> then a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-syntaxerror">SyntaxError</a> <em title="must" class="rfc2119">must</em> be thrown. Otherwise set the created <a class="internalDFN" href="#dfn-object-store">object store</a>'s
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is set to the value of <var>keyPath</var>.
|
|
</p>
|
|
<p>
|
|
If the <var>optionalParameters</var> parameter is specified, and <code>autoIncrement</code> is set to true, and
|
|
the <code>keyPath</code> parameter is specified to the empty string, or specified to an <code>Array</code>
|
|
and one of the items is an empty string, this function <em title="must" class="rfc2119">must</em> throw a <code>InvalidAccessError</code> exception.
|
|
</p>
|
|
<p>
|
|
In some implementations it's possible for the implementation to run into problems
|
|
after queuing up an operation to create the <a class="internalDFN" href="#dfn-object-store" title="object store">objectStore</a> after the <code>createObjectStore</code> function has returned.
|
|
For example in implementations where metadata about the newly created <a class="internalDFN" href="#dfn-object-store" title="object store">objectStore</a> is inserted into the database asynchronously,
|
|
or where the implementation might need to ask the user for permission for quota reasons.
|
|
Such implementations <em title="must" class="rfc2119">must</em> still create and return an <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> object. Instead,
|
|
once the implementation realizes that creating the <a class="internalDFN" href="#dfn-object-store" title="object store">objectStore</a> has failed, it <em title="must" class="rfc2119">must</em> abort the transaction
|
|
using the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of a new <a class="internalDFN" href="#dfn-object-store">object store</a></td></tr><tr><td class="prmName">optionalParameters</td><td class="prmType"><code><a>IDBObjectStoreParameters</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-options-object">options object</a> whose attributes are optional parameters to this function.
|
|
<code>keyPath</code> specifies the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> of the new
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>. If the attribute is <code>null</code>,
|
|
no <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is
|
|
specified and thus keys are <a class="internalDFN" href="#dfn-out-of-line">out-of-line</a>.
|
|
<code>autoIncrement</code> specifies whether the <a class="internalDFN" href="#dfn-object-store">object store</a>
|
|
created should have a <a class="internalDFN" href="#dfn-key-generator">key generator</a>.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> callback. Also occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">An <a class="internalDFN" href="#dfn-object-store">object store</a> with the same name, compared in a
|
|
case-sensitive manner, already exists in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. </td></tr><tr><td class="excCodeName"><code>InvalidAccessError</code></td><td class="excCodeDesc">If autoIncrement is set to true, and keyPath either is the empty string, or an <code>Array</code> containing the empty string.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></code></div></dd><dt id="widl-IDBDatabase-deleteObjectStore-void-DOMString-name"><code>deleteObjectStore</code></dt><dd>
|
|
<p>
|
|
This method destroys the <a class="internalDFN" href="#dfn-object-store">object store</a> with the given name in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. If this function is called from
|
|
outside a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a> callback, or if this
|
|
function is called on a <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> object other than that transactions
|
|
<a title="transaction conection">connection</a>, the implementation <em title="must" class="rfc2119">must</em> throw a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror"><code>InvalidStateError</code></a>.
|
|
</p>
|
|
<p>
|
|
This method synchronously modifies the
|
|
<a href="#widl-IDBDatabase-objectStoreNames">IDBDatabase.objectStoreNames</a> property. However it
|
|
only changes the <a href="#widl-IDBDatabase-objectStoreNames">IDBDatabase.objectStoreNames</a>
|
|
property on the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance on which it was called.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of an existing
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a> callback.
|
|
Also occurs if a request is made on a source object that has been deleted or removed.
|
|
</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">There is no <a class="internalDFN" href="#dfn-object-store">object store</a> with the given name, compared in a
|
|
case-sensitive manner, in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBDatabase-transaction-IDBTransaction-any-storeNames-unsigned-short-mode"><code>transaction</code></dt><dd>
|
|
<p>
|
|
This method, when called <em title="must" class="rfc2119">must</em> execute the
|
|
<a class="internalDFN" href="#dfn-create-a-transaction" title="create a transaction">steps for creating a transaction</a> in an asychronous
|
|
fashion. The <var>storeNames</var> and <var>mode</var> arguments are
|
|
forwarded to the algorithm as-is. The <var>callback</var> argument is set to null.
|
|
The <var>timeout</var> argument is set to infinite.
|
|
The <var>connection</var> argument is set to the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> that the
|
|
<code>transaction()</code> method was called on.
|
|
</p>
|
|
<p>
|
|
The method returns an <a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a> object representing the <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
returned by the steps above.
|
|
</p>
|
|
<p>
|
|
This method <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> if called before the
|
|
<code>success</code> event for a <a href="#widl-IDBFactory-open-IDBOpenDBRequest-DOMString-name-unsigned-long-long-version">open</a> call has been dispatched.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">storeNames</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The names of <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> and
|
|
<a class="internalDFN" href="#dfn-index" title="index">indexes</a> in the <a class="internalDFN" href="#dfn-scope">scope</a> of the new
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a></td></tr><tr><td class="prmName">mode</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc"> The <a class="internalDFN" href="#dfn-mode">mode</a> for isolating access to data inside the given
|
|
<a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a>. If this parameter is not provided, the default
|
|
access <a class="internalDFN" href="#dfn-mode">mode</a> is <code>READ_ONLY</code>.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
The close() method has been called on this <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance.
|
|
Also occurs if a request is made on a source object that has been deleted or removed.
|
|
</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a class="internalDFN" href="#dfn-database">database</a>.</td></tr><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value for the <a class="internalDFN" href="#dfn-mode">mode</a> parameter is invalid.</td></tr><tr><td class="excCodeName"><code>InvalidAccessError</code></td><td class="excCodeDesc">The function was called with an empty list of store names</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="object-store">
|
|
<h4><span class="secno">3.2.5 </span>Object Store</h4>
|
|
<a class="internalDFN" href="#dfn-object-store" title="object store">Object store</a> objects implement the following
|
|
interface:
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBObjectStore">interface <span class="idlInterfaceID">IDBObjectStore</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStore-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStore-keyPath">keyPath</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMStringList</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStore-indexNames">indexNames</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStore-transaction">transaction</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-put-IDBRequest-any-value-any-key">put</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-add-IDBRequest-any-value-any-key">add</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-delete-IDBRequest-any-key">delete</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-get-IDBRequest-any-key">get</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-clear-IDBRequest">clear</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-openCursor-IDBRequest-any-range-unsigned-short-direction">openCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-createIndex-IDBIndex-DOMString-name-DOMString-keyPath-IDBIndexParameters-optionalParameters">createIndex</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">keyPath</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>IDBIndexParameters</a></span> <span class="idlParamName">optionalParameters</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-index-IDBIndex-DOMString-name">index</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-deleteIndex-void-DOMString-indexName">deleteIndex</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">indexName</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStore-count-IDBRequest-any-key">count</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-6">Attributes</h5><dl class="attributes"><dt id="widl-IDBObjectStore-indexNames"><code>indexNames</code> of type <span class="idlAttrType"><a>DOMStringList</a></span>, readonly</dt><dd>
|
|
On getting, provide a list of the names of <a class="internalDFN" href="#dfn-index" title="index">indexes</a> on
|
|
objects in this <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStore-keyPath"><code>keyPath</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a>
|
|
of this <a class="internalDFN" href="#dfn-object-store">object store</a>. If this attribute is <code>null</code>,
|
|
the application <em title="must" class="rfc2119">must</em> provide a key value for each modification operation.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStore-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of this
|
|
object store.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStore-transaction"><code>transaction</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a></span>, readonly</dt><dd>
|
|
On getting, returns the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="internalDFN" href="#dfn-object-store">object store</a> belongs to.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-4">Methods</h5><dl class="methods"><dt id="widl-IDBObjectStore-add-IDBRequest-any-value-any-key"><code>add</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this IDBObjectStore belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If any of the following conditions are true, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and
|
|
the <var>key</var> parameter was provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a>out-of-line keys</a> and has no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the <var>key</var> parameter was not provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> yields a value and
|
|
that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> but no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> does not yield a value.
|
|
</li>
|
|
<li>
|
|
The <var>key</var> parameter was provided but does not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is a string,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value, and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is an <code>Array</code>,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> any of the items in their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the structure clone algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and return the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a>
|
|
as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
|
|
<var>key</var>, and with the <var>no-overwrite flag</var> flag set to true.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The value to be stored in the <a class="internalDFN" href="#dfn-record">record</a></td></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The key used to identify the <a class="internalDFN" href="#dfn-record">record</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the associated <a class="internalDFN" href="#dfn-transaction">transaction</a> is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The calculated key for the insertion was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>. Also thrown if the
|
|
calculated key for any of the indexes which belong to this object store had a calculated
|
|
key which was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a></td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-clear-IDBRequest"><code>clear</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this IDBObjectStore belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the
|
|
<a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as
|
|
<var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-clearing-an-object-store">steps for clearing an object store</a> as <var>operation</var>, using
|
|
this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>store</var>.
|
|
</p>
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is READ_ONLY.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-count-IDBRequest-any-key"><code>count</code></dt><dd>
|
|
<p>
|
|
If the optional <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var>.
|
|
If provided, use the <var>key</var> parameter as <var>key</var>, otherwise, use undefined as <var>key</var>.
|
|
If the result of the algorithm is <strong>null</strong> return <code>0</code> (zero) as the result for the request.
|
|
Otherwise, use the return <a class="internalDFN" href="#dfn-cursor">cursor</a> to determine the total number of objects that share the
|
|
<a class="internalDFN" href="#dfn-key-1">key</a> or <a class="internalDFN" href="#dfn-key-range">key range</a> and return that value as the result for the request.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
|
|
Key identifying the record to be retrieved.
|
|
This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter is not a valid <a class="internalDFN" href="#dfn-key-1">key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-createIndex-IDBIndex-DOMString-name-DOMString-keyPath-IDBIndexParameters-optionalParameters"><code>createIndex</code></dt><dd>
|
|
<p>
|
|
This method creates and returns a new <a class="internalDFN" href="#dfn-index">index</a> with the given name and parameters in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. If this function is called from
|
|
outside a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a> callback, the implementation
|
|
<em title="must" class="rfc2119">must</em> throw an <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> exception.
|
|
If an index with the same name already exists, the implementation <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-constrainterror">ConstraintError</a>.
|
|
Otherwise, the implementation <em title="must" class="rfc2119">must</em> create a new <a class="internalDFN" href="#dfn-index">index</a> and return an <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> object representing it. The created
|
|
index has its <a class="internalDFN" href="#dfn-unique">unique</a> and <a class="internalDFN" href="#dfn-multientry">multientry</a> flags are set to the values of the
|
|
<var>unique</var> and <var>multientry</var> properties in the <var>optionalParameters</var> argument.
|
|
</p>
|
|
<p>
|
|
If the <var>keyPath</var> argument is an <code>Array</code>, then each item in the array is
|
|
converted to a string. If <var>keyPath</var> is not an <code>Array</code>, it is converted to a
|
|
string.
|
|
</p>
|
|
<p>
|
|
If <var>keyPath</var> is an <code>Array</code> and any items in the array is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a>,
|
|
or if <var>keyPath</var> is a string and is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a> then a <code>DOMException</code>
|
|
of type <a class="internalDFN" href="#dfn-syntaxerror">SyntaxError</a> <em title="must" class="rfc2119">must</em> be thrown. If <var>keyPath</var> is
|
|
and <code>Array</code> and the <var>multientry</var> property in the <var>optionalParameters</var> is true,
|
|
then a <code>DOMException</code> of type <a>NotSupportedError</a> <em title="must" class="rfc2119">must</em> be thrown. Otherwise set the created <a class="internalDFN" href="#dfn-object-store">object store</a>'s
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is set to the value of <var>keyPath</var>.
|
|
</p>
|
|
<p>
|
|
The index that is requested to be created can contain constraints on the data allowed in the index's
|
|
<a class="internalDFN" href="#dfn-referenced">referenced</a> object store, such as requiring uniqueness of the values referenced by the
|
|
index's keyPath. If the <a class="internalDFN" href="#dfn-referenced">referenced</a> object store already contains data which violates these
|
|
constraints, this <em title="must not" class="rfc2119">must not</em> cause the implementation of createIndex to throw an exception or affect what it returns.
|
|
The implementation <em title="must" class="rfc2119">must</em> still create and return an <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> object.
|
|
Instead the implementation must queue up an operation to abort the <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> transaction
|
|
which was used for the createIndex call.
|
|
</p>
|
|
<p>
|
|
This method will synchronously modify the
|
|
<a href="#widl-IDBObjectStore-indexNames">IDBObjectStore.indexNames</a> property.
|
|
</p>
|
|
<p>
|
|
In some implementations it's possible for the implementation to asynchronously run into problems
|
|
creating the index after the createIndex function has returned.
|
|
For example in implementations where metadata about the newly created index is
|
|
queued up to be inserted into the database asynchronously,
|
|
or where the implementation might need to ask the user for permission for quota reasons.
|
|
Such implementations <em title="must" class="rfc2119">must</em> still create and return an <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> object. Instead,
|
|
once the implementation realizes that creating the index has failed, it <em title="must" class="rfc2119">must</em> abort the transaction
|
|
using the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of a new <a class="internalDFN" href="#dfn-index">index</a></td></tr><tr><td class="prmName">keyPath</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> used by the new
|
|
<a class="internalDFN" href="#dfn-index">index</a></td></tr><tr><td class="prmName">optionalParameters</td><td class="prmType"><code><a>IDBIndexParameters</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-options-object">options object</a> whose attributes are optional parameters to this function.
|
|
<code>unique</code> specifies whether the <a class="internalDFN" href="#dfn-index">index</a>'s <a class="internalDFN" href="#dfn-unique">unique</a> flag is
|
|
set.
|
|
<code>multientry</code> specifies whether the <a class="internalDFN" href="#dfn-index">index</a>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is
|
|
set.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> callback. Also occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">An <a class="internalDFN" href="#dfn-index">index</a> with the same name, compared in a
|
|
case-sensitive manner, already exists in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. </td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a></code></div></dd><dt id="widl-IDBObjectStore-delete-IDBRequest-any-key"><code>delete</code></dt><dd>
|
|
<p>
|
|
This method throws a ReadOnlyError if the transaction which this IDBObjectStore belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>
|
|
or a <a class="internalDFN" href="#dfn-key-range">key range</a> this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for
|
|
asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-deleting-records-from-an-object-store">steps for deleting
|
|
records from an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a>
|
|
as <var>store</var> and the <var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p class="note">
|
|
Unlike other methods which take keys or key ranges, this method does <strong>not</strong> allow null to
|
|
be passed as key. This is to reduce the risk that a small bug would clear a whole object store.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the <a class="internalDFN" href="#dfn-record">record</a> to be deleted</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is READ_ONLY.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-deleteIndex-void-DOMString-indexName"><code>deleteIndex</code></dt><dd>
|
|
<p>
|
|
This method destroys the <a class="internalDFN" href="#dfn-index">index</a> with the given name in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. Note that this
|
|
method must only be called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> callback.
|
|
</p>
|
|
<p>
|
|
This method will synchronously modify the
|
|
<a href="#widl-IDBObjectStore-indexNames">IDBObjectStore.indexNames</a> property.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">indexName</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of an existing <a class="internalDFN" href="#dfn-index">index</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> callback.</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">There is no <a class="internalDFN" href="#dfn-index">index</a> with the given name, compared in a
|
|
case-sensitive manner, in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBObjectStore-get-IDBRequest-any-key"><code>get</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing
|
|
a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-value-from-an-object-store">steps for retrieving a value from an
|
|
object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>store</var> and the
|
|
<var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p class="note">
|
|
This function produces the same result if a record with the given key doesn't exist as when a record
|
|
exists, but has <code>undefined</code> as value. If you need to tell the two situations apart, you can use
|
|
<a href="#widl-IDBObjectStore-openCursor-IDBRequest-any-range-unsigned-short-direction">openCursor</a> with the same key. This will return a cursor with
|
|
<code>undefined</code> as value if a record exists, or no cursor if no such record exists.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the <a class="internalDFN" href="#dfn-record">record</a> to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retreives the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-index-IDBIndex-DOMString-name"><code>index</code></dt><dd>
|
|
Returns an <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> representing an <a class="internalDFN" href="#dfn-index">index</a> that is part of the
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>. Every call to this function on the same
|
|
<a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance and with the same <var>name</var> returns the same <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> instance.
|
|
However the retured <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> instance is specific to this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance. If this
|
|
function is called on a different <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance, a different <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> instance is
|
|
returned. A result of this is that different <a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a>s use different <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> instances
|
|
to represent the same <a class="internalDFN" href="#dfn-index">index</a>.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of an existing <a class="internalDFN" href="#dfn-index">index</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">There is no <a class="internalDFN" href="#dfn-index">index</a> with the given name, compared in a
|
|
case-sensitive manner, in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a></code></div></dd><dt id="widl-IDBObjectStore-openCursor-IDBRequest-any-range-unsigned-short-direction"><code>openCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>. The cursor
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValue"><code>IDBCursorWithValue</code></a> interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> <em title="must" class="rfc2119">must</em> be set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a>
|
|
created by these steps. The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the
|
|
<a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed <a class="internalDFN" href="#dfn-key-range">key range</a> or a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBObjectStore-put-IDBRequest-any-value-any-key"><code>put</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this IDBObjectStore belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If any of the following conditions are true, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and
|
|
the <var>key</var> parameter was provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a>out-of-line keys</a> and has no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the <var>key</var> parameter was not provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> yields a value and
|
|
that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> but no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> does not yield a value.
|
|
</li>
|
|
<li>
|
|
The <var>key</var> parameter was provided but does not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is a string,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value, and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is an <code>Array</code>,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> any of the items in their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and return the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a>
|
|
as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
|
|
<var>key</var>, and with the <var>no-overwrite flag</var> flag set to false.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The value to be stored in the <a class="internalDFN" href="#dfn-record">record</a></td></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The key used to identify the <a class="internalDFN" href="#dfn-record">record</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the associated <a class="internalDFN" href="#dfn-transaction">transaction</a> is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The calculated key for the insertion was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>. Also thrown if the
|
|
calculated key for any of the indexes which belong to this object store had a calculated
|
|
key which was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a></td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="index">
|
|
<h4><span class="secno">3.2.6 </span>Index</h4>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-index" title="index">Index</a> objects implement the following interface:
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBIndex">interface <span class="idlInterfaceID">IDBIndex</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBIndex-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></span> <span class="idlAttrName"><a href="#widl-IDBIndex-objectStore">objectStore</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBIndex-keyPath">keyPath</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBIndex-multientry">multientry</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBIndex-unique">unique</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndex-openCursor-IDBRequest-any-range-unsigned-short-direction">openCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction">openKeyCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndex-get-IDBRequest-any-key">get</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndex-getKey-IDBRequest-any-key">getKey</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndex-count-IDBRequest-any-key">count</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-7">Attributes</h5><dl class="attributes"><dt id="widl-IDBIndex-keyPath"><code>keyPath</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> of this
|
|
<a class="internalDFN" href="#dfn-index">index</a>. If this attribute is <code>null</code>,
|
|
this <a class="internalDFN" href="#dfn-index">index</a> is not <a>auto-populated</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndex-multientry"><code>multientry</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-multientry">multientry</a> flag of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndex-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a title="index name">name</a> of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndex-objectStore"><code>objectStore</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></span>, readonly</dt><dd>
|
|
On getting, returns a reference to the <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance for the
|
|
<a class="internalDFN" href="#dfn-referenced">referenced</a> object store in this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a>'s transaction. This <em title="must" class="rfc2119">must</em>
|
|
return the same <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance as was used to get a reference
|
|
to this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndex-unique"><code>unique</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-unique">unique</a> flag of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-5">Methods</h5><dl class="methods"><dt id="widl-IDBIndex-count-IDBRequest-any-key"><code>count</code></dt><dd>
|
|
<p>
|
|
If the optional <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var>.
|
|
If provided, use the <var>key</var> parameter as <var>key</var>, otherwise, use undefined as <var>key</var>.
|
|
If the result of the algorithm is <strong>null</strong> return <code>0</code> (zero) as the result for the request.
|
|
Otherwise, use the return <a class="internalDFN" href="#dfn-cursor">cursor</a> to determine the total number of objects that share the
|
|
<a class="internalDFN" href="#dfn-key-1">key</a> or <a class="internalDFN" href="#dfn-key-range">key range</a> and return that value as the result for the request.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
|
|
Key identifying the record to be retrieved.
|
|
This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter is not a valid <a class="internalDFN" href="#dfn-key-1">key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBIndex-get-IDBRequest-any-key"><code>get</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a>
|
|
and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-referenced-value-from-an-index">steps for retrieving a referenced value from an
|
|
index</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> as <var>index</var> and the
|
|
<var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p class="note">
|
|
This function produces the same result if a record with the given key doesn't exist as when a record
|
|
exists, but has <code>undefined</code> as value. If you need to tell the two situations apart, you can use
|
|
<a href="#widl-IDBIndex-openCursor-IDBRequest-any-range-unsigned-short-direction">openCursor</a> with the same key. This will return a cursor with
|
|
<code>undefined</code> as value if a record exists, or no cursor if no such record exists.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the record to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retreives the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBIndex-getKey-IDBRequest-any-key"><code>getKey</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a>
|
|
and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-value-from-an-index">steps for retrieving a value from an
|
|
index</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> as <var>index</var> and the
|
|
<var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the record to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retreives the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBIndex-openCursor-IDBRequest-any-range-unsigned-short-direction"><code>openCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>.
|
|
The cursor <em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValue"><code>IDBCursorWithValue</code></a> interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> is set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing
|
|
a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed <a class="internalDFN" href="#dfn-key-range">key range</a> or a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>. The cursor
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> interface, but <em title="must not" class="rfc2119">must not</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValue"><code>IDBCursorWithValue</code></a> interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> is set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing
|
|
a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed <a class="internalDFN" href="#dfn-key-range">key range</a> or a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="cursor">
|
|
<h4><span class="secno">3.2.7 </span>Cursor</h4>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-cursor" title="cursor">Cursor</a> objects implement the following interface:
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBCursor">interface <span class="idlInterfaceID">IDBCursor</span> {
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursor-NEXT">NEXT</a></span> = <span class="idlConstValue">0</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursor-NEXT_NO_DUPLICATE">NEXT_NO_DUPLICATE</a></span> = <span class="idlConstValue">1</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursor-PREV">PREV</a></span> = <span class="idlConstValue">2</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursor-PREV_NO_DUPLICATE">PREV_NO_DUPLICATE</a></span> = <span class="idlConstValue">3</span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Object</a></span> <span class="idlAttrName"><a href="#widl-IDBCursor-source">source</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-IDBCursor-direction">direction</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBCursor-key">key</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBCursor-primaryKey">primaryKey</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBCursor-update-IDBRequest-any-value">update</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBCursor-advance-void-unsigned-long-count">advance</a></span> (<span class="idlParam">[<span class="extAttr">EnforceRange</span>] <span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">count</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBCursor-continue-void-any-key">continue</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBCursor-delete-IDBRequest">delete</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-8">Attributes</h5><dl class="attributes"><dt id="widl-IDBCursor-direction"><code>direction</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>
|
|
On getting, provide the traversal <a class="internalDFN" href="#dfn-direction">direction</a> of the <a class="internalDFN" href="#dfn-cursor">cursor</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBCursor-key"><code>key</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>Returns the cursor's current <a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a>.
|
|
Note that if this property returns an object (specifically an <code>Array</code>), it returns the same
|
|
object instance every time it is inspected, until the cursor's <a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> is changed.
|
|
This means that if the object is modified,
|
|
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
|
|
does not modify the contents of the database.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBCursor-primaryKey"><code>primaryKey</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>Returns the cursor's current <a class="internalDFN" href="#dfn-effective-key">effective key</a>.
|
|
Note that if this property returns an object (specifically an <code>Array</code>), it returns the same
|
|
object instance every time it is inspected, until the cursor's <a class="internalDFN" href="#dfn-effective-key">effective key</a> is changed.
|
|
This means that if the object is modified,
|
|
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
|
|
does not modify the contents of the database.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBCursor-source"><code>source</code> of type <span class="idlAttrType"><a>Object</a></span>, readonly</dt><dd>
|
|
On getting, returns the <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> or <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a>
|
|
which this cursor is iterating. This function
|
|
never returns null or throws an exception, even if the
|
|
cursor is currently being iterated, has iterated past its end,
|
|
or its transaction is not <a class="internalDFN" href="#dfn-active">active</a>.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-6">Methods</h5><dl class="methods"><dt id="widl-IDBCursor-advance-void-unsigned-long-count"><code>advance</code></dt><dd>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a>.
|
|
However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the
|
|
<a class="internalDFN" href="#dfn-request">request</a> originally created when this cursor was created. The <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag
|
|
on the request is set to false before the request is returned. The steps are run with the cursor's
|
|
<a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> as <var>source</var>. The <var>operation</var>
|
|
runs the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> <var>count</var> number of times
|
|
with null as <var>key</var> and this cursor as <var>cursor</var>.
|
|
</p>
|
|
<p>
|
|
Before this method returns, unless an exception was thrown, it sets the <a class="internalDFN" href="#dfn-got-value">got value</a> flag on the cursor to false.
|
|
</p>
|
|
<p>
|
|
Calling this method more than once before new cursor data has been loaded is not allowed
|
|
and results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown.
|
|
For example, calling <code>continue()</code> twice from the same onsuccess handler
|
|
results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown on the second call.
|
|
</p>
|
|
<p>
|
|
If the value for <code>count</code> is <code>0</code> (zero) or a negative number, this method <em title="must" class="rfc2119">must</em>
|
|
throw a <code>DOMException</code> of type <a>TypeError</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">count</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The number of advances forward the cursor should make.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value passed into the <code>count</code> parameter was zero or a negative number.</td></tr><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor is currently being iterated, or has iterated past its end.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBCursor-continue-void-any-key"><code>continue</code></dt><dd>
|
|
<p>
|
|
If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false, this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
If the <var>key</var> parameter is specified and fulfills any of these conditions this
|
|
method <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>The parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</li>
|
|
<li>
|
|
The parameter is <a class="internalDFN" href="#dfn-less-than">less than</a> or <a>equal to this cursor's </a><a class="internalDFN" href="#dfn-position">position</a>
|
|
and this cursor's <a class="internalDFN" href="#dfn-direction">direction</a> is NEXT or NEXT_NO_DUPLICATE.
|
|
</li>
|
|
<li>
|
|
The parameter is <a class="internalDFN" href="#dfn-greater-than">greater than</a> or <a>equal to this cursor's </a><a class="internalDFN" href="#dfn-position">position</a>
|
|
and this cursor's <a class="internalDFN" href="#dfn-direction">direction</a> is PREV or PREV_NO_DUPLICATE.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a>.
|
|
However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the
|
|
<a class="internalDFN" href="#dfn-request">request</a> originally created when this cursor was created. The <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag
|
|
on the request is set to false before the request is returned. The steps are run with the cursor's
|
|
<a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using this cursor as <var>cursor</var> and the <var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p>
|
|
Before this method returns, unless an exception was thrown, it sets the <a class="internalDFN" href="#dfn-got-value">got value</a> flag on the cursor to false.
|
|
</p>
|
|
<p>
|
|
Calling this method more than once before new cursor data has been loaded is not allowed
|
|
and results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown.
|
|
For example, calling <code>continue()</code> twice from the same onsuccess handler
|
|
results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown on the second call.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The next key to position this <a class="internalDFN" href="#dfn-cursor">cursor</a> at</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor is currently being iterated, or has iterated past its end.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was specified but did not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBCursor-delete-IDBRequest"><code>delete</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this IDBCursor belongs to
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false,
|
|
or if this cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> is thrown.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the
|
|
<a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps. The steps are run with this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> as <var>source</var>
|
|
and the <a class="internalDFN" href="#dfn-steps-for-deleting-records-from-an-object-store">steps for deleting records from an object store</a> as <var>operation</var>, using this cursor's
|
|
<a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> and <a class="internalDFN" href="#dfn-effective-key">effective key</a> as <var>store</var> and <var>key</var> respectively.
|
|
</p>
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to
|
|
is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> or the cursor
|
|
is currently being iterated or has iterated past the end.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd><dt id="widl-IDBCursor-update-IDBRequest-any-value"><code>update</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this IDBCursor belongs to
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false or if this
|
|
cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a>. This method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>. If the <a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> of this cursor uses <a>in-line</a>
|
|
keys and <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a>
|
|
of the <var>value</var> parameter results in a different value than the cursor's <a class="internalDFN" href="#dfn-effective-key">effective key</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
</p>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and
|
|
return the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this IDBCursor as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this cursor's
|
|
<a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> as <var>store</var>, the created clone as <var>value</var>,
|
|
this cursor's <a class="internalDFN" href="#dfn-effective-key">effective key</a> as <var>key</var>, and with the <var>no-overwrite flag</var>
|
|
flag set to false.
|
|
</p>
|
|
<p class="note">
|
|
A result of running the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for storing a record into an object store</a> is that if the record
|
|
has been deleted since the cursor moved to it, a new record will be created.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The new value to store at the current position.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to
|
|
is <code>READ_ONLY</code></td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Thrown if cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> or if the cursor
|
|
is currently being iterated or has iterated past the end.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc"> The underlying <a class="internalDFN" href="#dfn-object-store">object store</a> uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and the property in <var>value</var>
|
|
at the object store's <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> does not match the key in this <a class="internalDFN" href="#dfn-cursor">cursor</a>'s
|
|
<a class="internalDFN" href="#dfn-position">position</a>.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd></dl></div><div class="section"><h5 id="constants-1">Constants</h5><dl class="constants"><dt id="widl-IDBCursor-NEXT"><code>NEXT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically increasing
|
|
order of keys.
|
|
</dd><dt id="widl-IDBCursor-NEXT_NO_DUPLICATE"><code>NEXT_NO_DUPLICATE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, not including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically increasing
|
|
order of keys. For every key with duplicate values, only the first
|
|
record is yielded.
|
|
</dd><dt id="widl-IDBCursor-PREV"><code>PREV</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically decreasing
|
|
order of keys.
|
|
</dd><dt id="widl-IDBCursor-PREV_NO_DUPLICATE"><code>PREV_NO_DUPLICATE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, not including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically decreasing
|
|
order of keys. For every key with duplicate values, only the first
|
|
record is yielded.
|
|
</dd></dl></div>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBCursorWithValue">interface <span class="idlInterfaceID">IDBCursorWithValue</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a></span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBCursorWithValue-value">value</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-9">Attributes</h5><dl class="attributes"><dt id="widl-IDBCursorWithValue-value"><code>value</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>Returns the cursor's current <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>.
|
|
Note that if this property returns an object, it returns the same
|
|
object instance every time it is inspected, until the cursor's <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a> is changed.
|
|
This means that if the object is modified,
|
|
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
|
|
does not modify the contents of the database.<div><em>No exceptions.</em></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="transaction">
|
|
<h4><span class="secno">3.2.8 </span>Transaction</h4>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<p>
|
|
<a class="internalDFN" href="#dfn-transaction" title="transaction">Transaction</a> objects implement the following interface:
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBTransaction">interface <span class="idlInterfaceID">IDBTransaction</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransaction-READ_ONLY">READ_ONLY</a></span> = <span class="idlConstValue">0</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransaction-READ_WRITE">READ_WRITE</a></span> = <span class="idlConstValue">1</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransaction-VERSION_CHANGE">VERSION_CHANGE</a></span> = <span class="idlConstValue">2</span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-IDBTransaction-mode">mode</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a></span> <span class="idlAttrName"><a href="#widl-IDBTransaction-db">db</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></span> <span class="idlMethName"><a href="#widl-IDBTransaction-objectStore-IDBObjectStore-DOMString-name">objectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBTransaction-abort-void">abort</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBTransaction-onabort">onabort</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBTransaction-oncomplete">oncomplete</a></span>;</span>
|
|
<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
|
|
attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-IDBTransaction-onerror">onerror</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-10">Attributes</h5><dl class="attributes"><dt id="widl-IDBTransaction-db"><code>db</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a></span>, readonly</dt><dd>The <a class="internalDFN" href="#dfn-database">database</a> <a class="internalDFN" href="#dfn-connection">connection</a> of which this <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
is a part
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBTransaction-mode"><code>mode</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>On getting, provide the <a class="internalDFN" href="#dfn-mode">mode</a> for isolating access to data inside
|
|
the <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> that are in the
|
|
<a class="internalDFN" href="#dfn-scope">scope</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBTransaction-onabort"><code>onabort</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>abort event</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBTransaction-oncomplete"><code>oncomplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>complete event</a>.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBTransaction-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>The event handler for the <a>error event</a>.<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-7">Methods</h5><dl class="methods"><dt id="widl-IDBTransaction-abort-void"><code>abort</code></dt><dd>
|
|
If this <a class="internalDFN" href="#dfn-transaction">transaction</a> is <a title="transaction finish">finished</a>, throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
Otherwise this method sets the transactions's <a class="internalDFN" href="#dfn-active">active</a> flag to false and
|
|
<a title="transaction abort">aborts</a> the transaction by running the
|
|
<a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a> with
|
|
with the error attribute set to a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-aborterror">AbortError</a>.
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">If this <a class="internalDFN" href="#dfn-transaction">transaction</a> has already been committed or aborted.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBTransaction-objectStore-IDBObjectStore-DOMString-name"><code>objectStore</code></dt><dd>
|
|
Returns an <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> representing an <a class="internalDFN" href="#dfn-object-store">object store</a> that is part of the
|
|
to the <a class="internalDFN" href="#dfn-scope">scope</a> of this <a class="internalDFN" href="#dfn-transaction">transaction</a>. Every call to this function on the same
|
|
<a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a> instance and with the same <var>name</var> returns the same <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance.
|
|
However the returned <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance is specific to this <a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a>. If this
|
|
function is called on a different <a class="idlType" href="#idl-def-IDBTransaction"><code>IDBTransaction</code></a>, a different <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> instance is returned.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The requested <a class="internalDFN" href="#dfn-object-store">object store</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">
|
|
If the requested <a class="internalDFN" href="#dfn-object-store">object store</a> is not in this
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>'s <a class="internalDFN" href="#dfn-scope">scope</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a></code></div></dd></dl></div><div class="section"><h5 id="constants-2">Constants</h5><dl class="constants"><dt id="widl-IDBTransaction-READ_ONLY"><code>READ_ONLY</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>Modification operations are not allowed in the <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
in this mode.</dd><dt id="widl-IDBTransaction-READ_WRITE"><code>READ_WRITE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>Modification operations are allowed in the <a>transactions</a>
|
|
in this mode.</dd><dt id="widl-IDBTransaction-VERSION_CHANGE"><code>VERSION_CHANGE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>This mode is used solely for updating the version number of
|
|
transactions started using the <code>open()</code> method on the <a class="idlType" href="#idl-def-IDBFactory"><code>IDBFactory</code></a> interface.</dd></dl></div>
|
|
|
|
</div>
|
|
</div>
|
|
<div id="sync-database" class="section">
|
|
<h3><span class="secno">3.3 </span>Synchronous APIs</h3>
|
|
<p>
|
|
The synchronous database API methods provide a blocking access pattern to IndexedDB
|
|
databases. Since they block the calling thread they are only available from workers.
|
|
</p>
|
|
<div id="opening-sync" class="section">
|
|
<h4><span class="secno">3.3.1 </span>Opening a database</h4>
|
|
<p>
|
|
<a title="WorkerUtils" class="externalDFN"><code>WorkerUtils</code></a> objects <em title="must" class="rfc2119">must</em> implement the
|
|
<a class="idlType" href="#idl-def-IDBEnvironmentSync"><code>IDBEnvironmentSync</code></a> interface.
|
|
</p>
|
|
<pre class="idl"><span class="idlImplements"><a>WorkerUtils</a> implements <a class="idlType" href="#idl-def-IDBEnvironmentSync"><code>IDBEnvironmentSync</code></a>;</span></pre><div class="idlImplementsDesc">
|
|
</div>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBEnvironmentSync">[<span class="extAttr">NoInterfaceObject</span>]
|
|
interface <span class="idlInterfaceID">IDBEnvironmentSync</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBFactorySync"><code>IDBFactorySync</code></a></span> <span class="idlAttrName"><a href="#widl-IDBEnvironmentSync-indexedDBSync">indexedDBSync</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-11">Attributes</h5><dl class="attributes"><dt id="widl-IDBEnvironmentSync-indexedDBSync"><code>indexedDBSync</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBFactorySync"><code>IDBFactorySync</code></a></span>, readonly</dt><dd>This attribute provides applications a mechanism for accessing
|
|
capabilities of indexed databases.<div><em>No exceptions.</em></div></dd></dl></div>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBFactorySync">interface <span class="idlInterfaceID">IDBFactorySync</span> {
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBFactorySync-open-IDBDatabaseSync-DOMString-name-unsigned-long-long-version-IDBVersionChangeCallback-upgradeCallback-unsigned-long-timeout">open</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam">[<span class="extAttr">EnforceRange</span>] optional <span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">version</span></span>, <span class="idlParam">optional <span class="idlParamType"><a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a></span> <span class="idlParamName">upgradeCallback</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">timeout</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBFactorySync-deleteDatabase-void-DOMString-name">deleteDatabase</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>short</a></span> <span class="idlMethName"><a href="#widl-IDBFactorySync-cmp-short-any-first-any-second">cmp</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">first</span></span>, <span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">second</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="methods-8">Methods</h5><dl class="methods"><dt id="widl-IDBFactorySync-cmp-short-any-first-any-second"><code>cmp</code></dt><dd>
|
|
<p>
|
|
When invoked, this method <em title="must" class="rfc2119">must</em> compare two <a class="internalDFN" href="#dfn-key-1">key</a>s. The method returns 1 if the first key is
|
|
<a class="internalDFN" href="#dfn-greater-than">greater than</a> the second, -1 if the first is <a class="internalDFN" href="#dfn-less-than">less than</a> the second, and 0 if
|
|
the first is <a class="internalDFN" href="#dfn-equal-to">equal to</a> the second.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">first</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The first <a class="internalDFN" href="#dfn-key-1">key</a> to compare.</td></tr><tr><td class="prmName">second</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The second <a class="internalDFN" href="#dfn-key-1">key</a> to compare.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">One of the supplied keys was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>short</a></code></div></dd><dt id="widl-IDBFactorySync-deleteDatabase-void-DOMString-name"><code>deleteDatabase</code></dt><dd>
|
|
<p>
|
|
When invoked, this method synchronously runs the <a class="internalDFN" href="#dfn-steps-for-deleting-a-database">steps for deleting a database</a>.
|
|
Let <var>origin</var> be the origin of the <a class="idlType" href="#idl-def-IDBEnvironmentSync"><code>IDBEnvironmentSync</code></a> used to access
|
|
this <a class="idlType" href="#idl-def-IDBFactorySync"><code>IDBFactorySync</code></a> and <var>name</var> be the <var>name</var> argument passed
|
|
to this function.
|
|
</p>
|
|
<p>
|
|
If an error is returned from the steps above, then the implementation <em title="must" class="rfc2119">must</em>
|
|
throw a <code>DOMException</code> with its name and message set to appropriate values for the error.
|
|
</p>
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-database-name" title="database name">name</a> of the <a class="internalDFN" href="#dfn-database">database</a> to be deleted.</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBFactorySync-open-IDBDatabaseSync-DOMString-name-unsigned-long-long-version-IDBVersionChangeCallback-upgradeCallback-unsigned-long-timeout"><code>open</code></dt><dd>
|
|
<p>
|
|
When invoked, this method <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>
|
|
when it is called within the <a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a> of a <code>transaction</code>
|
|
method or the <a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a> of a <code>open</code> method. Otherwise this method
|
|
synchronously runs the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>. Let <var>origin</var> be the origin of the
|
|
<a class="idlType" href="#idl-def-IDBEnvironmentSync"><code>IDBEnvironmentSync</code></a> used to access this <a class="idlType" href="#idl-def-IDBFactorySync"><code>IDBFactorySync</code></a>, <var>name</var>, <var>version</var>
|
|
and <var>upgrade callback</var> be the <var>name</var>, <var>version</var> and <var>upgradeCallback</var>
|
|
arguments passed to this function.
|
|
</p>
|
|
<p>
|
|
If no version is specified and a database exists,
|
|
use the current database version and follow the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>.
|
|
If no version is specified and no database exists, set database version to 1,
|
|
follow the <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a>, and return a <a class="internalDFN" href="#dfn-database">database</a> without <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a>.
|
|
</p>
|
|
<p>
|
|
If a <var>timeout</var> parameter was supplied, then this limits the total waiting time allowed in
|
|
step 3 of <a class="internalDFN" href="#dfn-steps-for-opening-a-database">steps for opening a database</a> and step 4 of the <a class="internalDFN" href="#dfn-steps-for-running-a-version_change-transaction">steps for running a
|
|
<code>VERSION_CHANGE</code> transaction</a>. If more waiting time would be needed in order to progress,
|
|
then abort those algorithms and throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-timeouterror">TimeoutError</a>.
|
|
</p>
|
|
<p class="note">
|
|
The <var>timeout</var> parameter does not affect how long the <var>upgradeCallback</var> can run.
|
|
</p>
|
|
<p>
|
|
If an error is returned from the steps above, then the implementation <em title="must" class="rfc2119">must</em>
|
|
throw a <code>DOMException</code> with its name and message set to appropriate values for the error.
|
|
</p>
|
|
<p>
|
|
If the steps above are successful, the implementation <em title="must" class="rfc2119">must</em> create an <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a>
|
|
object representing the created <a class="internalDFN" href="#dfn-connection">connection</a> and return it.
|
|
</p>
|
|
<p class="note">
|
|
Processing a <code>open</code> call may take a long time as it could require running a
|
|
VERSION_CHANGE transaction which requires all other connections to the database to be closed, which
|
|
in turn may depend on user input or other long-running tasks. If blocking for a long period of time
|
|
is not acceptable for a given scenario then the asynchronous API should be used for version changes.
|
|
</p>
|
|
<p>
|
|
If the value for <code>version</code> is <code>0</code> (zero) or a negative number, this method <em title="must" class="rfc2119">must</em>
|
|
throw a <code>DOMException</code> of type <a>TypeError</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-database-name" title="database name">name</a> for the <a class="internalDFN" href="#dfn-database">database</a></td></tr><tr><td class="prmName">version</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a title="database version">version</a> for the <a class="internalDFN" href="#dfn-database">database</a></td></tr><tr><td class="prmName">upgradeCallback</td><td class="prmType"><code><a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Callback used if the <a>database version</a> needs to be upgraded before the
|
|
database can be opened.</td></tr><tr><td class="prmName">timeout</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">Defines a transaction timeout value in milliseconds that will limit the
|
|
how long waiting for the <code>VERSION_CHANGE</code> transaction. If the parameter is not provided,
|
|
the value of <var>timeout</var> is infinite.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
The <code>open</code> method was called within the <a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a> of a
|
|
<code>transaction</code> method or <a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a> of a
|
|
<code>open</code> method.
|
|
</td></tr><tr><td class="excCodeName"><code>TimeoutError</code></td><td class="excCodeDesc">
|
|
Was unable to open the database with the requested version within the given timeout period.
|
|
</td></tr><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value of <code>version</code> is <code>0</code> (zero) or a negative number.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
|
|
<div id="database-interface-sync" class="section">
|
|
<h4><span class="secno">3.3.2 </span>Database</h4>
|
|
<p>
|
|
A database object provides access to the schema and data of a particular database.
|
|
</p>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBDatabaseSync">interface <span class="idlInterfaceID">IDBDatabaseSync</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabaseSync-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabaseSync-version">version</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMStringList</a></span> <span class="idlAttrName"><a href="#widl-IDBDatabaseSync-objectStoreNames">objectStoreNames</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBDatabaseSync-createObjectStore-IDBObjectStoreSync-DOMString-name-IDBObjectStoreParameters-optionalParameters">createObjectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>IDBObjectStoreParameters</a></span> <span class="idlParamName">optionalParameters</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBDatabaseSync-deleteObjectStore-void-DOMString-name">deleteObjectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBDatabaseSync-transaction-void-any-storeNames-IDBTransactionCallback-callback-unsigned-short-mode-unsigned-long-timeout">transaction</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">storeNames</span></span>, <span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a></span> <span class="idlParamName">callback</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">mode</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">timeout</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBDatabaseSync-close-void">close</a></span> ();</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-12">Attributes</h5><dl class="attributes"><dt id="widl-IDBDatabaseSync-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-database-name" title="database name">name</a>
|
|
of the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. The function <em title="must" class="rfc2119">must</em>
|
|
return this name even if the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>.
|
|
In other words, the return value from this function
|
|
stays constant for the lifetime of the <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabaseSync-objectStoreNames"><code>objectStoreNames</code> of type <span class="idlAttrType"><a>DOMStringList</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return a list of names of the
|
|
<a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> currently in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
Once the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>, this
|
|
function <em title="must" class="rfc2119">must</em> return a snapshot of the list of names of the <a class="internalDFN" href="#dfn-object-store">object
|
|
store</a>s taken at the time when the
|
|
<a href="#widl-IDBDatabaseSync-close-void">close</a> method was called. Even if
|
|
other <a class="internalDFN" href="#dfn-connection">connection</a>s are later used to change the set of <a class="internalDFN" href="#dfn-object-store">object
|
|
store</a>s that exist in the <a class="internalDFN" href="#dfn-database">database</a>. In other words, the return
|
|
value from this function stays constant for the lifetime of the
|
|
<a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance except during a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
transaction if <a href="#widl-IDBDatabaseSync-createObjectStore-IDBObjectStoreSync-DOMString-name-IDBObjectStoreParameters-optionalParameters">createObjectStore</a>
|
|
or <a href="#widl-IDBDatabaseSync-deleteObjectStore-void-DOMString-name">deleteObjectStore</a>
|
|
is called on this <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance itself.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBDatabaseSync-version"><code>version</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
|
|
On getting, this attribute <em title="must" class="rfc2119">must</em> return the <a class="internalDFN" href="#dfn-version">version</a> of this
|
|
<a class="internalDFN" href="#dfn-database">database</a>. This attribute has the empty string value when the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a> is first created.
|
|
Once the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on the <a class="internalDFN" href="#dfn-connection">connection</a>, this
|
|
function <em title="must" class="rfc2119">must</em> return a snapshot of the <a class="internalDFN" href="#dfn-version">version</a> taken when the
|
|
<a href="#widl-IDBDatabase-close-void">close</a> method was called. Even if
|
|
other <a class="internalDFN" href="#dfn-connection">connection</a>s are later used to change the <a class="internalDFN" href="#dfn-version">version</a> of the
|
|
<a class="internalDFN" href="#dfn-database">database</a>. In other words, the return value from this function
|
|
stays constant for the lifetime of the <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-9">Methods</h5><dl class="methods"><dt id="widl-IDBDatabaseSync-close-void"><code>close</code></dt><dd>
|
|
This method synchronously performs the <a class="internalDFN" href="#dfn-steps-for-closing-a-database-connection">steps for closing a database connection</a> and returns once
|
|
the database has been closed.
|
|
<div><em>No parameters.</em></div><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBDatabaseSync-createObjectStore-IDBObjectStoreSync-DOMString-name-IDBObjectStoreParameters-optionalParameters"><code>createObjectStore</code></dt><dd>
|
|
<p>
|
|
This method creates and returns a new <a class="internalDFN" href="#dfn-object-store">object store</a> with the
|
|
given name in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. This method
|
|
should only be called from inside a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</p>
|
|
<p>
|
|
This method synchronously modifies the
|
|
<a href="#widl-IDBDatabaseSync-objectStoreNames">IDBDatabaseSync.objectStoreNames</a> property. However it
|
|
only modifies the <a href="#widl-IDBDatabaseSync-objectStoreNames">IDBDatabaseSync.objectStoreNames</a>
|
|
property on the <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance on which it was called.
|
|
</p>
|
|
<p>
|
|
If the <var>optionalParameters</var> argument is specified and has a <code>keyPath</code> property
|
|
which is not <code>null</code>, then set <var>keyPath</var> to the value
|
|
of this property. If <var>keyPath</var> is an <code>Array</code>, then each item in the array is
|
|
converted to a string. If <var>keyPath</var> is not an <code>Array</code>, it is converted to a
|
|
string.
|
|
</p>
|
|
<p>
|
|
If <var>keyPath</var> is an <code>Array</code> and any items in the array is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a>,
|
|
or if <var>keyPath</var> is a string and is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a> then a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-syntaxerror">SyntaxError</a> <em title="must" class="rfc2119">must</em> be thrown. Otherwise set the created <a class="internalDFN" href="#dfn-object-store">object store</a>'s
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is set to the value of <var>keyPath</var>.
|
|
</p>
|
|
<p>
|
|
If the <var>optionalParameters</var> parameter is specified, and <code>autoIncrement</code> is set to true, and
|
|
the <code>keyPath</code> parameter is specified to the empty string, or specified to an <code>Array</code>
|
|
and one of the items is an empty string, this function <em title="must" class="rfc2119">must</em> throw a <code>InvalidAccessError</code> exception.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of a new <a class="internalDFN" href="#dfn-object-store">object store</a></td></tr><tr><td class="prmName">optionalParameters</td><td class="prmType"><code><a>IDBObjectStoreParameters</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-options-object">options object</a> whose attributes are optional parameters to this function.
|
|
<code>keyPath</code> specifies the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> of the new
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>. If the attribute is <code>null</code> no <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is
|
|
specified and thus keys are <a class="internalDFN" href="#dfn-out-of-line">out-of-line</a>.
|
|
<code>autoIncrement</code> specifies
|
|
whether the <a class="internalDFN" href="#dfn-object-store">object store</a> created should have a <a class="internalDFN" href="#dfn-key-generator">key generator</a>.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
Also occurs if a request is made on a source object that has been deleted or removed.
|
|
</td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">If an <a class="internalDFN" href="#dfn-object-store">object store</a> with the same name, compared in a case-sensitive
|
|
manner, already exists in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a>
|
|
<a class="internalDFN" href="#dfn-database">database</a>.</td></tr><tr><td class="excCodeName"><code>InvalidAccessError</code></td><td class="excCodeDesc">If autoIncrement is set to true, and keyPath either is the empty string, or an <code>Array</code> containing the empty string.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></code></div></dd><dt id="widl-IDBDatabaseSync-deleteObjectStore-void-DOMString-name"><code>deleteObjectStore</code></dt><dd>
|
|
<p>
|
|
This method destroys an <a class="internalDFN" href="#dfn-object-store">object store</a> with the
|
|
given name as well as all <a class="internalDFN" href="#dfn-index" title="index">indexes</a> that are
|
|
<a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> that <a class="internalDFN" href="#dfn-object-store">object store</a>. This method
|
|
should only be called from inside a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</p>
|
|
<p>
|
|
This method synchronously modifies the
|
|
<a href="#widl-IDBDatabaseSync-objectStoreNames">IDBDatabaseSync.objectStoreNames</a> property. However it
|
|
only modifies the <a href="#widl-IDBDatabaseSync-objectStoreNames">IDBDatabaseSync.objectStoreNames</a>
|
|
property on the <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> instance on which it was called.
|
|
</p>
|
|
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of an existing
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a> callback.
|
|
Also occurs if a request is made on a source object that has been deleted or removed.
|
|
</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">
|
|
If the <a class="internalDFN" href="#dfn-object-store">object store</a> with the given name, compared in a
|
|
case-sensitive manner, does not already exist
|
|
in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBDatabaseSync-transaction-void-any-storeNames-IDBTransactionCallback-callback-unsigned-short-mode-unsigned-long-timeout"><code>transaction</code></dt><dd>
|
|
<p>
|
|
This method, when called <em title="must" class="rfc2119">must</em> execute the
|
|
<a class="internalDFN" href="#dfn-create-a-transaction" title="create a transaction">steps for creating a transaction</a> in a sychronous
|
|
fashion. The <var>storeNames</var>, <var>callback</var>, <var>mode</var>, and
|
|
<var>timeout</var> arguments are forwarded to the algorithm as-is. The <var>connection</var>
|
|
argument is set to the <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a> that the <code>transaction()</code> method was
|
|
called on.
|
|
</p>
|
|
<p>
|
|
The method returns an <a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a> object representing the <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
returned by the steps above.
|
|
</p>
|
|
<p>
|
|
This method <em title="must" class="rfc2119">must</em> throw an <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>
|
|
when it is called within the <a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a> of a <code>transaction</code> method or the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a> of a <code>open</code> method.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">storeNames</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The names of <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> and
|
|
<a class="internalDFN" href="#dfn-index" title="index">indexes</a> in the <a class="internalDFN" href="#dfn-scope">scope</a> of the new
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a></td></tr><tr><td class="prmName">callback</td><td class="prmType"><code><a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">A callback which will be called with the newly created transaction. When the callback returns,
|
|
the transaction is committed.</td></tr><tr><td class="prmName">mode</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
|
|
The <a class="internalDFN" href="#dfn-mode">mode</a> for isolating access to data inside the given
|
|
<a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a>. If this parameter is not provided, the default
|
|
access <a class="internalDFN" href="#dfn-mode">mode</a> is <code>READ_ONLY</code>.
|
|
</td></tr><tr><td class="prmName">timeout</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The interval in milliseconds which this operation is allowed to
|
|
take to reserve all the <a class="internalDFN" href="#dfn-database">database</a> objects identified in the new
|
|
<a class="internalDFN" href="#dfn-transaction" title="transaction">transaction's</a> <a class="internalDFN" href="#dfn-scope">scope</a>. The default
|
|
is user agent specific</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TimeoutError</code></td><td class="excCodeDesc">
|
|
If <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">starting</a> the transaction takes longer than the specified timeout.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">
|
|
The <code>close()</code> method has been called on this <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> instance.
|
|
Also thrown when The <code>transaction()</code> method was called within the
|
|
<a class="idlType" href="#idl-def-IDBTransactionCallback"><code>IDBTransactionCallback</code></a> of a <code>transaction</code> method or the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeCallback"><code>IDBVersionChangeCallback</code></a> of a <code>open</code> method.</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a class="internalDFN" href="#dfn-database">database</a>.</td></tr><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value for the <a class="internalDFN" href="#dfn-mode">mode</a> parameter is invalid.</td></tr><tr><td class="excCodeName"><code>InvalidAccessError</code></td><td class="excCodeDesc">The function was called with an empty list of store names</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="transaction-callback">
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBTransactionCallback">[<span class="extAttr">NoInterfaceObject, Callback</span>]
|
|
interface <span class="idlInterfaceID">IDBTransactionCallback</span> {
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBTransactionCallback-transactionStarted-void-IDBTransactionSync-transaction">transactionStarted</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></span> <span class="idlParamName">transaction</span></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="methods-10">Methods</h5><dl class="methods"><dt id="widl-IDBTransactionCallback-transactionStarted-void-IDBTransactionSync-transaction"><code>transactionStarted</code></dt><dd>
|
|
Called once the transaction is allowed to run. The actions taken in this function make up
|
|
the body of the transaction.
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">transaction</td><td class="prmType"><code><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The newly started transaction</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="versionchange-callback">
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBVersionChangeCallback">[<span class="extAttr">NoInterfaceObject, Callback</span>]
|
|
interface <span class="idlInterfaceID">IDBVersionChangeCallback</span> {
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBVersionChangeCallback-transactionStarted-void-IDBTransactionSync-transaction-unsigned-long-long-oldVersion">transactionStarted</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></span> <span class="idlParamName">transaction</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">oldVersion</span></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="methods-11">Methods</h5><dl class="methods"><dt id="widl-IDBVersionChangeCallback-transactionStarted-void-IDBTransactionSync-transaction-unsigned-long-long-oldVersion"><code>transactionStarted</code></dt><dd>
|
|
Called if a database upgrade is needed once the transaction used to upgrade the database is allowed to run.
|
|
The actions taken in this function make up the body of the transaction.
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">transaction</td><td class="prmType"><code><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The newly started transaction</td></tr><tr><td class="prmName">oldVersion</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The version that the database had before the upgrade was needed.</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="object-store-sync">
|
|
<h4><span class="secno">3.3.3 </span>Object Store</h4>
|
|
<div class="example"><div class="exampleHeader">Example</div>
|
|
<p>
|
|
In the following example, we set up an <a class="internalDFN" href="#dfn-object-store">object store</a> to use the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> <em>id</em>. This
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a> is also designed to use a <a class="internalDFN" href="#dfn-key-generator">key generator</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var db = indexedDBSync.open('AddressBook', 1, function(trans, oldVersion) {
|
|
trans.db.createObjectStore('Contact', 'id', true);
|
|
});
|
|
</code></pre></div></div>
|
|
<p>
|
|
Using this <a class="internalDFN" href="#dfn-database">database</a>, we can store records in the <em>Contact</em>
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var tx = db.transaction();
|
|
var store = tx.objectStore('Contact');
|
|
var contact = store.add({name: 'Lincoln', number: '7012'});
|
|
// contact.id === 1
|
|
</code></pre></div></div>
|
|
<p>
|
|
A stored value can be retrieved using the same key used by the
|
|
first put operation.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var contact = store.get(1);
|
|
// contact.name === 'Lincoln'</code></pre></div></div>
|
|
<p>
|
|
A put operation will overwrite the record stored by the first
|
|
add operation with the same <a class="internalDFN" href="#dfn-key-1">key</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var abraham = {id: 1, name: 'Abraham', number: '2107'};
|
|
store.put(abraham);</code></pre></div></div>
|
|
<p>
|
|
Now when the object store is read with the same key, the result
|
|
is different compared to the object read earlier.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var contact = store.get(1);
|
|
// contact.id === 1 && contact.name === 'Abraham';</code></pre></div></div>
|
|
<p>
|
|
Additionally, all the <a>records</a> of an <a class="internalDFN" href="#dfn-object-store">object store</a>
|
|
matching a certain <a class="internalDFN" href="#dfn-key-range">key range</a> can be retrieved in key order.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var range = new IDBKeyRange.bound(2, 4);
|
|
var cursor = store.openCursor(range);
|
|
// each value is a contact and each key is the id for that
|
|
// contact whose id is between 2 and 4, both inclusive
|
|
cursor.continue();</code></pre></div></div>
|
|
</div>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBObjectStoreSync">interface <span class="idlInterfaceID">IDBObjectStoreSync</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStoreSync-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStoreSync-keyPath">keyPath</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMStringList</a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStoreSync-indexNames">indexNames</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></span> <span class="idlAttrName"><a href="#widl-IDBObjectStoreSync-transaction">transaction</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>any</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-put-any-any-value-any-key">put</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>any</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-add-any-any-value-any-key">add</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>boolean</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-delete-boolean-any-key">delete</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>any</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-get-any-any-key">get</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-clear-void">clear</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-createIndex-IDBIndexSync-DOMString-name-DOMString-keyPath-IDBIndexParameters-optionalParameters">createIndex</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">keyPath</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>IDBIndexParameters</a></span> <span class="idlParamName">optionalParameters</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-index-IDBIndexSync-DOMString-name">index</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-deleteIndex-void-DOMString-indexName">deleteIndex</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">indexName</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction">openCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>unsigned short</a></span> <span class="idlMethName"><a href="#widl-IDBObjectStoreSync-count-unsigned-short-any-key">count</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-13">Attributes</h5><dl class="attributes"><dt id="widl-IDBObjectStoreSync-indexNames"><code>indexNames</code> of type <span class="idlAttrType"><a>DOMStringList</a></span>, readonly</dt><dd>
|
|
On getting, provide a list of the names of <a class="internalDFN" href="#dfn-index" title="index">indexes</a> on
|
|
objects in this <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStoreSync-keyPath"><code>keyPath</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a>
|
|
of this <a class="internalDFN" href="#dfn-object-store">object store</a>. If this attribute is <code>null</code>,
|
|
the application <em title="must" class="rfc2119">must</em> provide a key value for each modification operation.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStoreSync-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-object-store-name" title="object store name">name</a> of this
|
|
object store.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBObjectStoreSync-transaction"><code>transaction</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a></span>, readonly</dt><dd>
|
|
On getting, returns the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="internalDFN" href="#dfn-object-store">object store</a> belongs to.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-12">Methods</h5><dl class="methods"><dt id="widl-IDBObjectStoreSync-add-any-any-value-any-key"><code>add</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If any of the following conditions are true, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and
|
|
the <var>key</var> parameter was provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a>out-of-line keys</a> and has no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the <var>key</var> parameter was not provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> yields a value and
|
|
that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> but no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> does not yield a value.
|
|
</li>
|
|
<li>
|
|
The <var>key</var> parameter was provided but does not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is a string,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value, and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is an <code>Array</code>,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> any of the items in their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a> and return the <a class="internalDFN" href="#dfn-key-1">key</a> of the stored object.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a>
|
|
as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
|
|
<var>key</var>, and with the <var>no-overwrite flag</var> flag set to true.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The value to be stored in the record</td></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The key used to identify the record</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the associated <a class="internalDFN" href="#dfn-transaction">transaction</a> is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The calculated key for the insertion was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>. Also thrown if the
|
|
calculated key for any of the indexes which belong to this object store had a calculated
|
|
key which was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a></td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">A record
|
|
exists in this <a class="internalDFN" href="#dfn-object-store">object store</a> for the key <var>key</var> parameter, or another record
|
|
in this <a class="internalDFN" href="#dfn-object-store">object store</a> has the same value for the <a>keyPath</a> of a unique <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>any</a></code></div></dd><dt id="widl-IDBObjectStoreSync-clear-void"><code>clear</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>. The steps
|
|
are run with this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the
|
|
<a class="internalDFN" href="#dfn-steps-for-clearing-an-object-store">steps for clearing an object store</a> as <var>operation</var>, using
|
|
this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>store</var>.
|
|
</p>
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is READ_ONLY.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBObjectStoreSync-count-unsigned-short-any-key"><code>count</code></dt><dd>
|
|
<p>
|
|
If the optional <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStore"><code>IDBObjectStore</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var>.
|
|
If provided, use the <var>key</var> parameter as <var>key</var>, otherwise, use undefined as <var>key</var>.
|
|
If the result of the algorithm is <strong>null</strong> return <code>0</code> (zero) as the result for the request.
|
|
Otherwise, use the return <a class="internalDFN" href="#dfn-cursor">cursor</a> to determine the total number of objects that share the
|
|
<a class="internalDFN" href="#dfn-key-1">key</a> or <a class="internalDFN" href="#dfn-key-range">key range</a> and return that value as the result for the request.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
|
|
Key identifying the record to be retrieved.
|
|
This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter is not a valid <a class="internalDFN" href="#dfn-key-1">key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>unsigned short</a></code></div></dd><dt id="widl-IDBObjectStoreSync-createIndex-IDBIndexSync-DOMString-name-DOMString-keyPath-IDBIndexParameters-optionalParameters"><code>createIndex</code></dt><dd>
|
|
<p>
|
|
This creates and returns a new <a class="internalDFN" href="#dfn-index">index</a> with the given name and parameters in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. Note that this method must only
|
|
be called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a> <a class="internalDFN" href="#dfn-transaction">transaction</a>. The created
|
|
index has its <a class="internalDFN" href="#dfn-unique">unique</a> and <a class="internalDFN" href="#dfn-multientry">multientry</a> flags are set to the values of the
|
|
<var>unique</var> and <var>multientry</var> properties in the <var>optionalParameters</var> argument.
|
|
</p>
|
|
<p>
|
|
If the <var>keyPath</var> argument is an <code>Array</code>, then each item in the array is
|
|
converted to a string. If <var>keyPath</var> is not an <code>Array</code>, it is converted to a
|
|
string.
|
|
</p>
|
|
<p>
|
|
If <var>keyPath</var> is an <code>Array</code> and any items in the array is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a>,
|
|
or if <var>keyPath</var> is a string and is not a <a class="internalDFN" href="#dfn-valid-key-path">valid key path</a>, then a <code>DOMException</code>
|
|
of type <a class="internalDFN" href="#dfn-syntaxerror">SyntaxError</a> <em title="must" class="rfc2119">must</em> be thrown. If <var>keyPath</var> is
|
|
and <code>Array</code> and the <var>multientry</var> property in the <var>optionalParameters</var> is true,
|
|
then a <code>DOMException</code> of type <a>NotSupportedError</a> <em title="must" class="rfc2119">must</em> be thrown. Otherwise set the created <a class="internalDFN" href="#dfn-object-store">object store</a>'s
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> is set to the value of <var>keyPath</var>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of a new <a class="internalDFN" href="#dfn-index">index</a></td></tr><tr><td class="prmName">keyPath</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> used by the new
|
|
<a class="internalDFN" href="#dfn-index">index</a></td></tr><tr><td class="prmName">optionalParameters</td><td class="prmType"><code><a>IDBIndexParameters</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-options-object">options object</a> whose attributes are optional parameters to this function.
|
|
<code>unique</code> specifies whether the <a class="internalDFN" href="#dfn-index">index</a>'s <a class="internalDFN" href="#dfn-unique">unique</a> flag is
|
|
set.
|
|
<code>multientry</code> specifies whether the <a class="internalDFN" href="#dfn-index">index</a>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is
|
|
set.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>. Also occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">An <a class="internalDFN" href="#dfn-index">index</a> with the same name, compared in a
|
|
case-sensitive manner, already exists in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
Also thrown when creating a unique <a class="internalDFN" href="#dfn-index">index</a> on top of an <a class="internalDFN" href="#dfn-object-store">object store</a>
|
|
that already contains records that violate the unique constraint.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a></code></div></dd><dt id="widl-IDBObjectStoreSync-delete-boolean-any-key"><code>delete</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>
|
|
or a <a class="internalDFN" href="#dfn-key-range">key range</a> this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-deleting-records-from-an-object-store">steps for deleting
|
|
records from an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a>
|
|
as <var>store</var> and the <var>key</var> parameter as <var>key</var>. The function returns the result
|
|
of running these steps.
|
|
</p>
|
|
<p class="note">
|
|
Unlike other methods which take keys or key ranges, this method does <strong>not</strong> allow null to
|
|
be passed as key. This is to reduce the risk that a small bug would clear a whole object store.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the record to be deleted</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is READ_ONLY.</td></tr><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">A record did not exist in this <a class="internalDFN" href="#dfn-object-store">object store</a>
|
|
for the key <var>key</var> parameter.
|
|
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>boolean</a></code></div></dd><dt id="widl-IDBObjectStoreSync-deleteIndex-void-DOMString-indexName"><code>deleteIndex</code></dt><dd>
|
|
<p>
|
|
This method destroys the <a class="internalDFN" href="#dfn-index">index</a> with the given name in the
|
|
<a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>. Note that this
|
|
method must only be called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">indexName</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of an existing <a class="internalDFN" href="#dfn-index">index</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">
|
|
If the <a class="internalDFN" href="#dfn-index">index</a> with the given name does not exist
|
|
in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">This method was not called from a <a class="internalDFN" href="#dfn-version_change"><code>VERSION_CHANGE</code></a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBObjectStoreSync-get-any-any-key"><code>get</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing
|
|
a request</a> and returns the result of the operation. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-value-from-an-object-store">steps for retrieving a value from an
|
|
object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>store</var> and the
|
|
<var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p class="note">
|
|
This function produces the same result if a record with the given key doesn't exist as when a record
|
|
exists, but has <code>undefined</code> as value. If you need to tell the two situations apart, you can use
|
|
<a href="#widl-IDBObjectStoreSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction">openCursor</a> with the same key. This will return a cursor with
|
|
<code>undefined</code> as value if a record exists, or no cursor if no such record exists.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the <a class="internalDFN" href="#dfn-record">record</a> to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retrieves the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>any</a></code></div></dd><dt id="widl-IDBObjectStoreSync-index-IDBIndexSync-DOMString-name"><code>index</code></dt><dd>
|
|
Returns an <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> representing an <a class="internalDFN" href="#dfn-index">index</a> that is part of the
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>. Every call to this function on the same
|
|
<a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance and with the same <var>name</var> returns the same <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> instance.
|
|
However the retured <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> instance is specific to this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance. If this
|
|
function is called on a different <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance, a different <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> instance is
|
|
returned. A result of this is that different <a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a>s use different <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> instances
|
|
to represent the same <a class="internalDFN" href="#dfn-index">index</a>.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The <a title="index name">name</a> of an existing <a class="internalDFN" href="#dfn-index">index</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">
|
|
If the <a class="internalDFN" href="#dfn-index">index</a> with the given name does not exist
|
|
in the <a class="internalDFN" href="#dfn-connection" title="connection">connected</a> <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a></code></div></dd><dt id="widl-IDBObjectStoreSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction"><code>openCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>. The cursor
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a> interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> is set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a> and returns the result of the operation, in
|
|
this case an <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> object. The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the
|
|
<a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed <a class="internalDFN" href="#dfn-key-range">key range</a> or a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a></code></div></dd><dt id="widl-IDBObjectStoreSync-put-any-any-value-any-key"><code>put</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If any of the following conditions are true, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and
|
|
the <var>key</var> parameter was provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a>out-of-line keys</a> and has no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the <var>key</var> parameter was not provided.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> yields a value and
|
|
that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
The object store uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> but no <a class="internalDFN" href="#dfn-key-generator">key generator</a>
|
|
and the result of <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">object store's key path</a> does not yield a value.
|
|
</li>
|
|
<li>
|
|
The <var>key</var> parameter was provided but does not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is a string,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value, and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es <a class="internalDFN" href="#dfn-referenced" title="referenced">referencing</a> this object
|
|
store whose <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is an <code>Array</code>,
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> any of the items in their <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a>
|
|
on the <var>value</var> parameter yields a value and that value is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a> and return the result,
|
|
in this case the <a class="internalDFN" href="#dfn-key-1">key</a> of the stored object.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a>
|
|
as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
|
|
<var>key</var>, and with the <var>no-overwrite flag</var> flag set to false.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The value to be stored in the record</td></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The key used to identify the record</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the associated <a class="internalDFN" href="#dfn-transaction">transaction</a> is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The calculated key for the insertion was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>. Also thrown if the
|
|
calculated key for any of the indexes which belong to this object store had a calculated
|
|
key which was not a <a class="internalDFN" href="#dfn-valid-key">valid key</a></td></tr><tr><td class="excCodeName"><code>ConstraintError</code></td><td class="excCodeDesc">Another record in this <a class="internalDFN" href="#dfn-object-store">object store</a> has the same value for the <a>keyPath</a> of
|
|
a unique <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>any</a></code></div></dd></dl></div>
|
|
</div>
|
|
<div id="index-sync" class="section">
|
|
<h4><span class="secno">3.3.4 </span>Index</h4>
|
|
|
|
<div class="example"><div class="exampleHeader">Example</div>
|
|
<p>
|
|
An <a class="internalDFN" href="#dfn-index">index</a> can be created for retrieving records other than
|
|
by using record keys. Continuing the earlier example, an
|
|
index could be maintained on the <em>name</em> property of objects
|
|
in the <em>Contact</em> <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var db = indexedDBSync.open('AddressBook', 2, function(trans, oldVersion) {
|
|
if (oldVersion === 1) {
|
|
trans.db.createObjectStore('Contact', 'id', true);
|
|
}
|
|
var store = vtx.objectStore('Contact');
|
|
store.createIndex('ContactName', 'name', false);
|
|
});
|
|
</code></pre></div></div>
|
|
<p>
|
|
For example, the <em>id</em> of an object with the <em>name</em>
|
|
property value 'Lincoln' can be retrieved using the
|
|
<em>ContactName</em> <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var index = store.<a>openIndex</a>('ContactName');
|
|
var id = index.<a>get</a>('Lincoln');
|
|
// id === 1</code></pre></div></div>
|
|
<p>
|
|
Additionally, all the records of an <a class="internalDFN" href="#dfn-object-store">object store</a> matching
|
|
a certain range index keys can be retrieved in key order. When
|
|
objects are retrieved from the <em>Contact</em> <a class="internalDFN" href="#dfn-object-store">object store</a>,
|
|
they are arranged by the value of the <em>id</em> attribute. On the
|
|
other hand, when objects are retrieved using the <em>ContactName</em>
|
|
<a class="internalDFN" href="#dfn-index">index</a>, they are arranged by the value of the <em>name</em>
|
|
property.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var range = new <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.<a>bound</a>('L', 'M');
|
|
var cursor = index.<a>openCursor</a>(range);
|
|
// each value is a contact and each key is the name for that
|
|
// contact whose name's first letter is either L or M
|
|
cursor.<a>continue</a>();</code></pre></div></div>
|
|
<p>
|
|
If, on the other hand, we only want the names and keys but not the whole <em>Contact</em>
|
|
objects for a given range, then we can use a different mechanism for that.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var range = new <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.<a>bound</a>('L', 'M');
|
|
var cursor = index.<a>openKeyCursor</a>(range);
|
|
// each value is a contact id and each key is the name for that
|
|
// contact whose name's first letter is either L or M
|
|
cursor.<a>continue</a>();</code></pre></div></div>
|
|
</div>
|
|
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBIndexSync">interface <span class="idlInterfaceID">IDBIndexSync</span> {
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBIndexSync-name">name</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></span> <span class="idlAttrName"><a href="#widl-IDBIndexSync-objectStore">objectStore</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-IDBIndexSync-keyPath">keyPath</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBIndexSync-multientry">multientry</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-IDBIndexSync-unique">unique</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndexSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction">openCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBIndexSync-openKeyCursor-IDBCursorSync-any-range-unsigned-short-direction">openKeyCursor</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a>?</span> <span class="idlParamName">range</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">direction</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>any</a></span> <span class="idlMethName"><a href="#widl-IDBIndexSync-get-any-any-key">get</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>any</a></span> <span class="idlMethName"><a href="#widl-IDBIndexSync-getKey-any-any-key">getKey</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>unsigned short</a></span> <span class="idlMethName"><a href="#widl-IDBIndexSync-count-unsigned-short-any-key">count</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-14">Attributes</h5><dl class="attributes"><dt id="widl-IDBIndexSync-keyPath"><code>keyPath</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> of this
|
|
<a class="internalDFN" href="#dfn-index">index</a>. If this attribute is <code>null</code>,
|
|
this <a class="internalDFN" href="#dfn-index">index</a> is not <a>auto-populated</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndexSync-multientry"><code>multientry</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-multientry">multientry</a> flag of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndexSync-name"><code>name</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a title="index name">name</a> of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndexSync-objectStore"><code>objectStore</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></span>, readonly</dt><dd>
|
|
On getting, returns a reference to the <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance for the
|
|
<a class="internalDFN" href="#dfn-referenced">referenced</a> object store in this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a>'s transaction. This <em title="must" class="rfc2119">must</em>
|
|
return the same <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance as was used to get a reference
|
|
to this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBIndexSync-unique"><code>unique</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>
|
|
On getting, provide the <a class="internalDFN" href="#dfn-unique">unique</a> flag of this <a class="internalDFN" href="#dfn-index">index</a>.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-13">Methods</h5><dl class="methods"><dt id="widl-IDBIndexSync-count-unsigned-short-any-key"><code>count</code></dt><dd>
|
|
<p>
|
|
If the optional <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and returns the <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> created by these steps.
|
|
The steps are run with this <a class="idlType" href="#idl-def-IDBIndex"><code>IDBIndex</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var>.
|
|
If provided, use the <var>key</var> parameter as <var>key</var>, otherwise, use undefined as <var>key</var>.
|
|
If the result of the algorithm is <strong>null</strong> return <code>0</code> (zero) as the result for the request.
|
|
Otherwise, use the return <a class="internalDFN" href="#dfn-cursor">cursor</a> to determine the total number of objects that share the
|
|
<a class="internalDFN" href="#dfn-key-1">key</a> or <a class="internalDFN" href="#dfn-key-range">key range</a> and return that value as the result for the request.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
|
|
Key identifying the record to be retrieved.
|
|
This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.
|
|
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter is not a valid <a class="internalDFN" href="#dfn-key-1">key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>unsigned short</a></code></div></dd><dt id="widl-IDBIndexSync-get-any-any-key"><code>get</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>
|
|
and returns the result from that, in this case an object from the underlying store. The steps are
|
|
run with this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-referenced-value-from-an-index">steps
|
|
for retrieving a referenced value from an index</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a>
|
|
as <var>index</var> and the <var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
<p class="note">
|
|
This function produces the same result if a record with the given key doesn't exist as when a record
|
|
exists, but has <code>undefined</code> as value. If you need to tell the two situations apart, you can use
|
|
<a href="#widl-IDBIndexSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction">openCursor</a> with the same key. This will return a cursor with
|
|
<code>undefined</code> as value if a record exists, or no cursor if no such record exists.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the record to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retreives the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>any</a></code></div></dd><dt id="widl-IDBIndexSync-getKey-any-any-key"><code>getKey</code></dt><dd>
|
|
<p>
|
|
If the <var>key</var> parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>
|
|
and returns the result from that, in this case an index value (a <a class="internalDFN" href="#dfn-key-1">key</a>). The steps are
|
|
run with the <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> associated with this index as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-retrieving-a-value-from-an-index">steps
|
|
for retrieving a value from an index</a> as <var>operation</var>, using this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a>
|
|
as <var>index</var> and the <var>key</var> parameter as <var>key</var>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">Key identifying the record to be retrieved. This can also be an <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a> in which case
|
|
the function retreives the first existing value in that range.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>any</a></code></div></dd><dt id="widl-IDBIndexSync-openCursor-IDBCursorWithValueSync-any-range-unsigned-short-direction"><code>openCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>. The cursor
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a> interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> is set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing
|
|
a request</a> and returns the result, in this case a cursor object. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed a valid value.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a></code></div></dd><dt id="widl-IDBIndexSync-openKeyCursor-IDBCursorSync-any-range-unsigned-short-direction"><code>openKeyCursor</code></dt><dd>
|
|
<p>
|
|
If the <var>range</var> parameter is specified but is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a> or a <a class="internalDFN" href="#dfn-key-range">key range</a>,
|
|
this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>. Otherwise, this method creates a <a class="internalDFN" href="#dfn-cursor">cursor</a>. The cursor
|
|
<em title="must" class="rfc2119">must</em> implement the <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> interface and <em title="must not" class="rfc2119">must not</em> implement the <a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a>
|
|
interface.
|
|
</p>
|
|
<p>
|
|
The newly created cursor <em title="must" class="rfc2119">must</em> have an undefined <a class="internalDFN" href="#dfn-position">position</a>, a <a class="internalDFN" href="#dfn-direction">direction</a> set to the value
|
|
of the <var>direction</var> parameter, false as <a>iterable</a> flag value, and undefined
|
|
<a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>. The <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>
|
|
of the cursor is the <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> this function was called on.
|
|
</p>
|
|
<p>
|
|
If the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a> is set to that
|
|
range. Otherwise, if the <var>range</var> parameter is a <a class="internalDFN" href="#dfn-valid-key">valid key</a> then the cursor's <a class="internalDFN" href="#dfn-range">range</a>
|
|
is set to <a class="internalDFN" href="#dfn-key-range">key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
|
|
the cursor's key range is left as undefined.
|
|
</p>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing
|
|
a request</a> and returns the result, in this case a cursor object. The steps are run with this
|
|
<a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> as <var>operation</var>,
|
|
using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">range</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-key-range">key range</a> to use as the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a></td></tr><tr><td class="prmName">direction</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The <a class="internalDFN" href="#dfn-cursor">cursor</a>'s required <a class="internalDFN" href="#dfn-direction">direction</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The transaction this <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>range</var> parameter was not passed <a class="internalDFN" href="#dfn-key-range">key range</a> or a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a></code></div></dd></dl></div>
|
|
</div>
|
|
<div class="section" id="cursor-sync">
|
|
<h4><span class="secno">3.3.5 </span>Cursor</h4>
|
|
<p>
|
|
Using the synchronous API, an application can process all the records
|
|
in the <a class="internalDFN" href="#dfn-cursor">cursor</a>'s <a class="internalDFN" href="#dfn-range">range</a>.
|
|
</p>
|
|
<div class="example"><div class="exampleHeader">Example</div>
|
|
<p>
|
|
By default, a <a class="internalDFN" href="#dfn-cursor">cursor</a> walks over objects starting at the
|
|
first record and ending at the last record including
|
|
all the duplicates encountered along the way.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var tx = db.<a class="internalDFN" href="#dfn-transaction">transaction</a>('Contact');
|
|
var store = tx.<a>objectStore</a>('Contact');
|
|
var cursor = store.<a>openCursor</a>();
|
|
while(cursor.<a>continue</a>()) {
|
|
var value = cursor.value;
|
|
// act on each object or key
|
|
}
|
|
</code></pre></div></div>
|
|
|
|
<p>
|
|
To start at the last record and end in the first record, the cursor
|
|
should be created with the direction parameter <a class="idlType" href="#widl-IDBCursor-PREV"><code>PREV</code></a>.
|
|
</p>
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var cursor = store.<a>openCursor</a>(<a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a>.<a>PREV</a>);
|
|
while(cursor.<a>continue()</a>) {
|
|
// act on each object or key
|
|
}
|
|
</code></pre></div></div>
|
|
|
|
<p>
|
|
To start at a certain key and end in the last record, i.e.,
|
|
for a lower-bounded cursor, while skipping duplicates,
|
|
the cursor should be created with both the required
|
|
start key and the direction parameter.
|
|
</p>
|
|
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var range = <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.leftBound(key);
|
|
var cursor = store.<a>openCursor</a>(range, <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a>.<a>NEXT_NO_DUPLICATE</a>);
|
|
</code></pre></div></div>
|
|
|
|
<p>
|
|
It is also possible to create a bounded cursor, i.e., with
|
|
application-specified starting and ending points, the
|
|
cursor should be created with both the required keys.
|
|
If the range is inclusive of both keys, then additional
|
|
flags are required. In the following example, all keys
|
|
with values in the inclusive range (<code>start</code>,
|
|
<code>end</code>) are returned with all their duplicates,
|
|
from the beginning of the range to its end.
|
|
</p>
|
|
|
|
<div class="block"><div class="blockTitleDiv"><span class="blockTitle">ECMAScript</span></div><div class="blockContent"><pre class="code"><code class="es-code">var range = <a class="idlType" href="#idl-def-IDBKeyRange"><code>IDBKeyRange</code></a>.bound(start, end);
|
|
var cursor = objects.<a>openCursor</a>(range);
|
|
</code></pre></div></div>
|
|
</div>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBCursorSync">interface <span class="idlInterfaceID">IDBCursorSync</span> {
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursorSync-NEXT">NEXT</a></span> = <span class="idlConstValue">0</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursorSync-NEXT_NO_DUPLICATE">NEXT_NO_DUPLICATE</a></span> = <span class="idlConstValue">1</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursorSync-PREV">PREV</a></span> = <span class="idlConstValue">2</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBCursorSync-PREV_NO_DUPLICATE">PREV_NO_DUPLICATE</a></span> = <span class="idlConstValue">3</span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Object</a></span> <span class="idlAttrName"><a href="#widl-IDBCursorSync-source">source</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-IDBCursorSync-direction">direction</a></span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBCursorSync-primaryKey">primaryKey</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></span> <span class="idlMethName"><a href="#widl-IDBCursorSync-update-IDBRequest-any-value">update</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>boolean</a></span> <span class="idlMethName"><a href="#widl-IDBCursorSync-advance-boolean-unsigned-long-count">advance</a></span> (<span class="idlParam">[<span class="extAttr">EnforceRange</span>] <span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">count</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>boolean</a></span> <span class="idlMethName"><a href="#widl-IDBCursorSync-continue-boolean-any-key">continue</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>any</a></span> <span class="idlParamName">key</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>boolean</a></span> <span class="idlMethName"><a href="#widl-IDBCursorSync-delete-boolean">delete</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-15">Attributes</h5><dl class="attributes"><dt id="widl-IDBCursorSync-direction"><code>direction</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>
|
|
On getting, provide the traversal <a class="internalDFN" href="#dfn-direction">direction</a> of the <a class="internalDFN" href="#dfn-cursor">cursor</a>.
|
|
<div><em>No exceptions.</em></div></dd><dt id="widl-IDBCursorSync-primaryKey"><code>primaryKey</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>Returns the cursor's current <a class="internalDFN" href="#dfn-effective-key">effective key</a>.
|
|
Note that if this property returns an object (specifically an <code>Array</code>), it returns the same
|
|
object instance every time it is inspected, until the cursor is iterated.
|
|
This means that if the object is modified,
|
|
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
|
|
does not modify the contents of the database.<div><em>No exceptions.</em></div></dd><dt id="widl-IDBCursorSync-source"><code>source</code> of type <span class="idlAttrType"><a>Object</a></span>, readonly</dt><dd>
|
|
On getting, returns the <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> or <a class="idlType" href="#idl-def-IDBIndexSync"><code>IDBIndexSync</code></a>
|
|
which this cursor is iterating. This function
|
|
never returns null or throws an exception, even if the
|
|
cursor is currently being iterated, has iterated past its end,
|
|
or its transaction is not <a class="internalDFN" href="#dfn-active">active</a>.
|
|
<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-14">Methods</h5><dl class="methods"><dt id="widl-IDBCursorSync-advance-boolean-unsigned-long-count"><code>advance</code></dt><dd>
|
|
<p>
|
|
This method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>.
|
|
The steps are run with the cursor's <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> as <var>source</var>.
|
|
The <var>operation</var> runs the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</a> <var>count</var> number of times
|
|
with null as <var>key</var> and this cursor as <var>cursor</var>. If the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously
|
|
executing a request</a> returns a cursor, then this function returns <code>true</code>. Otherwise
|
|
this function returns <code>false</code>.
|
|
</p>
|
|
<p>
|
|
Before this method returns, unless an exception was thrown, it sets the <a class="internalDFN" href="#dfn-got-value">got value</a> flag in the cursor to false.
|
|
</p>
|
|
<p>
|
|
Calling this method more than once before new cursor data has been loaded is not allowed
|
|
and results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown.
|
|
For example, calling <code>continue()</code> twice from the same onsuccess handler
|
|
results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown on the second call.
|
|
</p>
|
|
<p>
|
|
If the value for <code>count</code> is <code>0</code> (zero) or a negative number, this method <em title="must" class="rfc2119">must</em>
|
|
throw a <code>DOMException</code> of type <a>TypeError</a>.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">count</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The number of advances forward the cursor should make.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TypeError</code></td><td class="excCodeDesc">The value passed into the <code>count</code> parameter was zero or a negative number.</td></tr><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor is currently being iterated, or has iterated past its end.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>boolean</a></code></div></dd><dt id="widl-IDBCursorSync-continue-boolean-any-key"><code>continue</code></dt><dd>
|
|
<p>
|
|
If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false, this method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
If the <var>key</var> parameter is specified and fulfills any of these conditions this
|
|
method <em title="must" class="rfc2119">must</em> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>:
|
|
</p>
|
|
<ul>
|
|
<li>The parameter is not a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</li>
|
|
<li>
|
|
The parameter is <a class="internalDFN" href="#dfn-less-than">less than</a> or <a>equal to this cursor's </a><a class="internalDFN" href="#dfn-position">position</a>
|
|
and this cursor's <a class="internalDFN" href="#dfn-direction">direction</a> is NEXT or NEXT_NO_DUPLICATE.
|
|
</li>
|
|
<li>
|
|
The parameter is <a class="internalDFN" href="#dfn-greater-than">greater than</a> or <a>equal to this cursor's </a><a class="internalDFN" href="#dfn-position">position</a>
|
|
and this cursor's <a class="internalDFN" href="#dfn-direction">direction</a> is PREV or PREV_NO_DUPLICATE.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>.
|
|
The steps are run with the cursor's <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-iterating-a-cursor">steps
|
|
for iterating a cursor</a> as <var>operation</var>, using the cursor this is called on as <var>cursor</var> and
|
|
the <var>key</var> parameter as <var>key</var>. If the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a> returns
|
|
a cursor, then this function returns <code>true</code>. Otherwise this function returns <code>false</code>.
|
|
</p>
|
|
<p>
|
|
Before this method returns, unless an exception was thrown, it sets the <a class="internalDFN" href="#dfn-got-value">got value</a> flag in the cursor to false.
|
|
</p>
|
|
<p>
|
|
Calling this method more than once before new cursor data has been loaded is not allowed
|
|
and results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown.
|
|
For example, calling <code>continue()</code> twice from the same onsuccess handler
|
|
results in a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> being thrown on the second call.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">The next key to position this <a class="internalDFN" href="#dfn-cursor">cursor</a> at</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor is currently being iterated, or has iterated past its end.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc">The <var>key</var> parameter was specified but did not contain a <a class="internalDFN" href="#dfn-valid-key">valid key</a>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>boolean</a></code></div></dd><dt id="widl-IDBCursorSync-delete-boolean"><code>delete</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a> if the transaction which this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> belongs to
|
|
has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY. If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false,
|
|
or if this cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a> is thrown.
|
|
</p>
|
|
<p>
|
|
Otherwise this method runs the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>. The steps are run
|
|
with this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-deleting-records-from-an-object-store">steps for deleting records from an
|
|
object store</a> as <var>operation</var>, using this cursor's <a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> and
|
|
<a class="internalDFN" href="#dfn-effective-key">effective key</a> as <var>store</var> and <var>key</var> respectively. The function returns the
|
|
result of running these steps.
|
|
</p>
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a> belongs to
|
|
is <code>READ_ONLY</code>.</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">The cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndexSync-openKeyCursor-IDBCursorSync-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> or the cursor
|
|
is currently being iterated or has iterated past the end.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>boolean</a></code></div></dd><dt id="widl-IDBCursorSync-update-IDBRequest-any-value"><code>update</code></dt><dd>
|
|
<p>
|
|
This method throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-readonlyerror">ReadOnlyError</a>
|
|
if the transaction which this IDBCursorSync belongs to has its <a class="internalDFN" href="#dfn-mode">mode</a> set to READ_ONLY.
|
|
If this cursor's <a class="internalDFN" href="#dfn-got-value">got value</a> flag is false or if this cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a>, this method
|
|
throws a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
If the <a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> of this cursor uses <a>in-line</a>
|
|
keys and <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluating</a> the <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a>
|
|
of the <var>value</var> parameter results in a different value than the cursor's <a class="internalDFN" href="#dfn-effective-key">effective key</a>,
|
|
this method throws <code>DOMException</code> of type <a class="internalDFN" href="#dfn-dataerror">DataError</a>.
|
|
</p>
|
|
<p>
|
|
Otherwise this method creates a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <var>value</var> parameter.
|
|
If the <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> algorithm throws an exception, that exception is rethrown.
|
|
Otherwise, run the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a> and return the result returned by these steps.
|
|
The steps are run with this IDBCursorSync as <var>source</var> and the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for
|
|
storing a record into an object store</a> as <var>operation</var>, using this cursor's
|
|
<a class="internalDFN" href="#dfn-effective-object-store">effective object store</a> as <var>store</var>, the created clone as <var>value</var>,
|
|
this cursor's <a class="internalDFN" href="#dfn-effective-key">effective key</a> as <var>key</var>, and with the <var>no-overwrite flag</var>
|
|
flag set to false.
|
|
</p>
|
|
<p class="note">
|
|
A result of running the <a class="internalDFN" href="#dfn-steps-for-storing-a-record-into-an-object-store">steps for storing a record into an object store</a> is that if the record
|
|
has been deleted since the cursor moved to it, a new record will be created.
|
|
</p>
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The new value to store at the current position.</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>TransactionInactiveError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to is not <a class="internalDFN" href="#dfn-active">active</a>.</td></tr><tr><td class="excCodeName"><code>ReadOnlyError</code></td><td class="excCodeDesc">The <a class="internalDFN" href="#dfn-mode">mode</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a> this <a class="idlType" href="#idl-def-IDBCursor"><code>IDBCursor</code></a> belongs to
|
|
is <code>READ_ONLY</code></td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Thrown if cursor was created using
|
|
<a class="idlType" href="#widl-IDBIndex-openKeyCursor-IDBRequest-any-range-unsigned-short-direction"><code>openKeyCursor</code></a> or if the cursor
|
|
is currently being iterated or has iterated past the end.</td></tr><tr><td class="excCodeName"><code>DataError</code></td><td class="excCodeDesc"> The underlying <a class="internalDFN" href="#dfn-object-store">object store</a> uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and the property in <var>value</var>
|
|
at the object store's <a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> does not match the key in this <a class="internalDFN" href="#dfn-cursor">cursor</a>'s
|
|
<a class="internalDFN" href="#dfn-position">position</a>.</td></tr><tr><td class="excCodeName"><code>DataCloneError</code></td><td class="excCodeDesc">The data being stored could not be cloned by the internal
|
|
structured cloning algorithm.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a></code></div></dd></dl></div><div class="section"><h5 id="constants-3">Constants</h5><dl class="constants"><dt id="widl-IDBCursorSync-NEXT"><code>NEXT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically increasing
|
|
order of keys.
|
|
</dd><dt id="widl-IDBCursorSync-NEXT_NO_DUPLICATE"><code>NEXT_NO_DUPLICATE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, not including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically increasing
|
|
order of keys. For every key with duplicate values, only the first
|
|
record is yielded.
|
|
</dd><dt id="widl-IDBCursorSync-PREV"><code>PREV</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically decreasing
|
|
order of keys.
|
|
</dd><dt id="widl-IDBCursorSync-PREV_NO_DUPLICATE"><code>PREV_NO_DUPLICATE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
|
|
indicates that this <a class="internalDFN" href="#dfn-cursor">cursor</a> should yield all records, not including
|
|
duplicates and its <a class="internalDFN" href="#dfn-direction">direction</a> is monotonically decreasing
|
|
order of keys. For every key with duplicate values, only the first
|
|
record is yielded.
|
|
</dd></dl></div>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBCursorWithValueSync">interface <span class="idlInterfaceID">IDBCursorWithValueSync</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-IDBCursorSync"><code>IDBCursorSync</code></a></span> {
|
|
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-IDBCursorWithValueSync-value">value</a></span>;</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-16">Attributes</h5><dl class="attributes"><dt id="widl-IDBCursorWithValueSync-value"><code>value</code> of type <span class="idlAttrType"><a>any</a></span></dt><dd>Returns the cursor's current <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a>.
|
|
Note that if this property returns an object, it returns the same
|
|
object instance every time it is inspected, until the cursor is iterated.
|
|
This means that if the object is modified,
|
|
those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object
|
|
does not modify the contents of the database.<div><em>No exceptions.</em></div></dd></dl></div>
|
|
</div>
|
|
<div id="transaction-sync" class="section">
|
|
<h4><span class="secno">3.3.6 </span>Transaction</h4>
|
|
<!-- TODO Add example. Should examples be in a separate section?-->
|
|
<p>
|
|
When an application <a class="internalDFN" href="#dfn-create-a-transaction" title="create a transaction">creates</a> a
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> synchronously, it blocks until the user agent is able
|
|
to reserve the required <a class="internalDFN" href="#dfn-database">database</a> <a>objects</a>.
|
|
</p>
|
|
<pre class="idl"><span class="idlInterface" id="idl-def-IDBTransactionSync">interface <span class="idlInterfaceID">IDBTransactionSync</span> {
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransactionSync-READ_ONLY">READ_ONLY</a></span> = <span class="idlConstValue">0</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransactionSync-READ_WRITE">READ_WRITE</a></span> = <span class="idlConstValue">1</span>;</span>
|
|
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-IDBTransactionSync-VERSION_CHANGE">VERSION_CHANGE</a></span> = <span class="idlConstValue">2</span>;</span>
|
|
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-IDBTransactionSync-mode">mode</a></span>;</span>
|
|
<span class="idlAttribute"> attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a></span> <span class="idlAttrName"><a href="#widl-IDBTransactionSync-db">db</a></span>;</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></span> <span class="idlMethName"><a href="#widl-IDBTransactionSync-objectStore-IDBObjectStoreSync-DOMString-name">objectStore</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">name</span></span>) raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-IDBTransactionSync-abort-void">abort</a></span> () raises (<span class="idlRaises"><a>DOMException</a></span>);</span>
|
|
};</span>
|
|
</pre><div class="section"><h5 id="attributes-17">Attributes</h5><dl class="attributes"><dt id="widl-IDBTransactionSync-db"><code>db</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a></span></dt><dd>The <a class="internalDFN" href="#dfn-database">database</a> <a class="internalDFN" href="#dfn-connection">connection</a> of which this <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
is a part<div><em>No exceptions.</em></div></dd><dt id="widl-IDBTransactionSync-mode"><code>mode</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>On getting, provide the <a class="internalDFN" href="#dfn-mode">mode</a> for isolating access to data inside
|
|
the <a class="internalDFN" href="#dfn-object-store" title="object store">object stores</a> that are in the
|
|
<a class="internalDFN" href="#dfn-scope">scope</a> of the <a class="internalDFN" href="#dfn-transaction">transaction</a>.<div><em>No exceptions.</em></div></dd></dl></div><div class="section"><h5 id="methods-15">Methods</h5><dl class="methods"><dt id="widl-IDBTransactionSync-abort-void"><code>abort</code></dt><dd>
|
|
If this <a class="internalDFN" href="#dfn-transaction">transaction</a> is <a title="transaction finish">finished</a>, throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
Otherwise this method sets the transactions's <a class="internalDFN" href="#dfn-active">active</a> flag to false and
|
|
<a title="transaction abort">aborts</a> the transaction by running the
|
|
<a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
It also sets the <var>error</var> attribute on the <a class="internalDFN" href="#dfn-transaction">transaction</a> to a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-aborterror">AbortError</a>.
|
|
|
|
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">If this <a class="internalDFN" href="#dfn-transaction">transaction</a> has already been committed or aborted.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-IDBTransactionSync-objectStore-IDBObjectStoreSync-DOMString-name"><code>objectStore</code></dt><dd>
|
|
Returns an <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> representing an <a class="internalDFN" href="#dfn-object-store">object store</a> that is within the <a class="internalDFN" href="#dfn-scope">scope</a> of this <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
Every call to this function on the same <a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a> instance and with the same <var>name</var> returns the same <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance.
|
|
However the retured <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance is specific to this <a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a>.
|
|
If this function is called on a different <a class="idlType" href="#idl-def-IDBTransactionSync"><code>IDBTransactionSync</code></a>, a different <a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a> instance is returned.
|
|
|
|
|
|
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">name</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">The requested <a class="internalDFN" href="#dfn-object-store">object store</a></td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>DOMException</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NotFoundError</code></td><td class="excCodeDesc">
|
|
If the requested <a class="internalDFN" href="#dfn-object-store">object store</a> is not in this
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>'s <a class="internalDFN" href="#dfn-scope">scope</a>.
|
|
</td></tr><tr><td class="excCodeName"><code>InvalidStateError</code></td><td class="excCodeDesc">Occurs if a request is made on a source object that has been deleted or removed.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a class="idlType" href="#idl-def-IDBObjectStoreSync"><code>IDBObjectStoreSync</code></a></code></div></dd></dl></div><div class="section"><h5 id="constants-4">Constants</h5><dl class="constants"><dt id="widl-IDBTransactionSync-READ_ONLY"><code>READ_ONLY</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>Modification operations are not allowed in the <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
in this mode.</dd><dt id="widl-IDBTransactionSync-READ_WRITE"><code>READ_WRITE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>Modification operations are allowed in the <a>transactions</a>
|
|
in this mode.</dd><dt id="widl-IDBTransactionSync-VERSION_CHANGE"><code>VERSION_CHANGE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>This mode is used solely for updating the version number of
|
|
transactions started using the <code>open()</code> method of <a class="idlType" href="#idl-def-IDBFactorySync"><code>IDBFactorySync</code></a>.</dd></dl></div>
|
|
<div class="note">
|
|
Applications <em title="must" class="rfc2119">must</em> not assume that committing the <a class="internalDFN" href="#dfn-transaction">transaction</a>
|
|
produces an instantaneously durable result. The user agent
|
|
<em title="may" class="rfc2119">may</em> delay flushing data to durable storage until an appropriate
|
|
time.
|
|
</div>
|
|
|
|
<p>
|
|
Once a <a class="internalDFN" href="#dfn-transaction">transaction</a> is aborted or committed, the <a class="internalDFN" href="#dfn-active">active</a>
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a> on this <a class="internalDFN" href="#dfn-database">database</a> <a class="internalDFN" href="#dfn-connection">connection</a> is removed.
|
|
A new <a class="internalDFN" href="#dfn-transaction">transaction</a> can be created to perform operations atomically.
|
|
</p>
|
|
</div> <!-- IDBTransaction -->
|
|
</div>
|
|
</div>
|
|
<div class="section" id="algorithms">
|
|
<!--OddPage--><h2><span class="secno">4. </span>Algorithms</h2>
|
|
<div class="section" id="opening">
|
|
<h3><span class="secno">4.1 </span>Opening a database</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-opening-a-database">steps for opening a database</dfn> are defined in the following steps. The algorithm in these steps
|
|
takes three required arguments: an <var>origin</var>, which requested the <a class="internalDFN" href="#dfn-database">database</a> to be opened,
|
|
a database <var>name</var>, and a database <var>version</var>. The algorithm also takes two optional
|
|
arguments, a <var>request</var> which represents a <a class="internalDFN" href="#dfn-request">request</a> used when opening the database is done by using
|
|
an asynchronous API or a <var>upgrade callback</var> which represents the callback used when opening the database
|
|
is done by using the synchronous API.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
If these steps fail for any reason, return an error with the appropriate type and abort
|
|
this algorithm.
|
|
</li>
|
|
<li>
|
|
If there is already a database with the given name from the origin <var>origin</var>, then
|
|
let <var>db</var> be that database.
|
|
</li>
|
|
<!--<li>
|
|
If <var>db</var> was found in the previous step, and it has a <a>version</a> higher than
|
|
<var>version</var>, then abort these steps and return a <a><code>VERSION_ERR</code></a> error.
|
|
Likewise, if at any point while running these steps, these steps are also running with the same
|
|
<var>origin</var> and <var>name</var>, but with a higher <var>version</var>, abort these steps and
|
|
return a <a><code>VERSION_ERR</code></a> error.
|
|
<div class="note">
|
|
<p>This can happen in for example the following four situations:</p>
|
|
<ul>
|
|
<li>
|
|
The database already has a version higher than the version requested to be opened.
|
|
</li>
|
|
<li>
|
|
Another call to <code>open</code> with a higher version is already in progress, but is
|
|
waiting for other connections to be closed before being able to fire the
|
|
<code>upgradeneeded</code> event.
|
|
</li>
|
|
<li>
|
|
While this call is waiting for other connections to be closed before being able to firing
|
|
the <code>upgradeneeded</code> event, another call to <code>open</code> is made with a
|
|
higher version.
|
|
</li>
|
|
<li>
|
|
Two calls to open happen at the same time with different version numbers.
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</li>-->
|
|
<li>
|
|
If <var>db</var> was found in previous step, wait until the following conditions are all fulfilled:
|
|
<ul>
|
|
<li>
|
|
No already existing <a class="internalDFN" href="#dfn-connection">connection</a>s to <var>db</var>, have
|
|
non-<a title="transaction finish">finished</a> VERSION_CHANGE <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
</li>
|
|
<li>
|
|
If <var>db</var> has its <a class="internalDFN" href="#dfn-delete-pending">delete pending</a> flag set, wait until <var>db</var> has
|
|
been deleted.
|
|
</li>
|
|
<li>
|
|
These steps are not run for any other <a class="internalDFN" href="#dfn-connection">connection</a>s with the same <var>origin</var>
|
|
and <var>name</var> but with a higher <var>version</var>.
|
|
</li>
|
|
</ul>
|
|
<p class="note">
|
|
If several connections with the same origin, name and version are opened at the same time,
|
|
and that version is a higher version that the database's current version, then once any of
|
|
those connections can proceed to the next step in this algorithm it will immediately start
|
|
a VERSION_CHANGE transaction. This prevents the other connections from proceeding until that
|
|
VERSION_CHANGE transaction is finished.
|
|
</p>
|
|
<p class="note">
|
|
This means that if two databases with the same name and origin, but with different versions, are
|
|
being opened at the same time, the one with the highest version will attempt to be opened first.
|
|
If it is able to successfully open, then the one with the lower version will receive an error.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
If no database with the given name from the origin <var>origin</var> was found, or if it was
|
|
deleted during the previous step, then create a <a class="internalDFN" href="#dfn-database">database</a> with name <var>name</var>,
|
|
with <code>0</code> as <a class="internalDFN" href="#dfn-version">version</a>, and with no <a class="internalDFN" href="#dfn-object-store">object store</a>s. Let <var>db</var>
|
|
be the new database.
|
|
</li>
|
|
<li>
|
|
If the <a class="internalDFN" href="#dfn-version">version</a> of <var>db</var> is higher than <var>version</var>, abort these steps and return
|
|
a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-versionerror">VersionError</a>.
|
|
</li>
|
|
<li>
|
|
Create a new <a class="internalDFN" href="#dfn-connection">connection</a> to <var>db</var> and let <var>connection</var> represent it.
|
|
</li>
|
|
<li>
|
|
If the <a class="internalDFN" href="#dfn-version">version</a> of <var>db</var> is lower than <var>version</var>, then run the
|
|
<a class="internalDFN" href="#dfn-steps-for-running-a-version_change-transaction">steps for running a <code>VERSION_CHANGE</code> transaction</a> using <var>connection</var>,
|
|
<var>version</var>, <var>request</var> and <var>upgrade callback</var>.
|
|
</li>
|
|
<li>
|
|
If the previous step resulted in an error, then return that error and abort these steps.
|
|
If the <code>VERSION_CHANGE</code> transaction in the previous step was aborted, or if
|
|
<var>connection</var> is <a class="internalDFN" href="#dfn-database-close-1" title="database close">closed</a>, return a
|
|
<code>DOMError</code> of type <a class="internalDFN" href="#dfn-aborterror">AbortError</a> and abort these steps.
|
|
In either of these cases, ensure that <var>connection</var> is <a class="internalDFN" href="#dfn-database-close-1" title="database close">closed</a>
|
|
by running the <a class="internalDFN" href="#dfn-steps-for-closing-a-database-connection">steps for closing a database connection</a> before these steps are aborted.
|
|
</li>
|
|
<li>
|
|
Return <var>connection</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="transaction-creation-steps" class="section">
|
|
<h3><span class="secno">4.2 </span>Transaction Creation steps</h3>
|
|
<p>
|
|
When the user agent is to <dfn id="dfn-create-a-transaction">create a <a class="internalDFN" href="#dfn-transaction">transaction</a></dfn>
|
|
it <em title="must" class="rfc2119">must</em> run the following steps. This algorithm takes five parameters:
|
|
A <a class="internalDFN" href="#dfn-connection"><var>connection</var></a>, a <a class="internalDFN" href="#dfn-mode"><var>mode</var></a>, a list of <var>storeNames</var> of
|
|
<a class="internalDFN" href="#dfn-object-store">object store</a>s to be included in the <a class="internalDFN" href="#dfn-scope">scope</a> of the transaction, a
|
|
<var>timeout</var> for the transaction <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">starting</a>,
|
|
and a <var>callback</var> parameter for synchronously created transactions.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If these steps are already running synchronously (a <a class="internalDFN" href="#dfn-transaction">transaction</a> was created within a
|
|
<a title="transaction-callback">transaction callback</a>), throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
</li>
|
|
<li>
|
|
If <var>storeNames</var> is of type <code>DOMStringList</code> or <code>Array</code> leave it as is. Otherwise,
|
|
interpret it as an <code>Array</code> with one value, and that value is the <a>stringified</a> version of
|
|
<var>storeNames</var>. If any of the strings in <var>storeNames</var> identifies an <a class="internalDFN" href="#dfn-object-store">object store</a> which doesn't
|
|
exist, throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-notfounderror">NotFoundError</a>. If <var>storeNames</var> is an empty list
|
|
throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidaccesserror">InvalidAccessError</a>.
|
|
</li>
|
|
<li>
|
|
If the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag is set on <var>connection</var> the throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-invalidstateerror">InvalidStateError</a>.
|
|
</li>
|
|
<li>
|
|
<a class="internalDFN" href="#dfn-transaction-create" title="transaction create">Create</a> a <a class="internalDFN" href="#dfn-transaction">transaction</a> using <var>connection</var> as
|
|
<a class="internalDFN" href="#dfn-connection">connection</a>, <var>mode</var> as <a class="internalDFN" href="#dfn-mode">mode</a>, and the <a class="internalDFN" href="#dfn-object-store">object store</a>s identified in
|
|
<var>storeNames</var> as <a class="internalDFN" href="#dfn-scope">scope</a>.
|
|
</li>
|
|
<li>
|
|
If these steps are running asynchronously, return the created <a class="internalDFN" href="#dfn-transaction">transaction</a> and queue up the the remaining steps.
|
|
When control is returned to the event loop, the implementation <em title="must" class="rfc2119">must</em> set the <a class="internalDFN" href="#dfn-active">active</a> flag to false.
|
|
</li>
|
|
<li>
|
|
Wait until the <a class="internalDFN" href="#dfn-transaction">transaction</a> can be <a class="internalDFN" href="#dfn-transaction-start" title="transaction start">started</a> according to the
|
|
<a class="internalDFN" href="#dfn-transaction-lifetime">transaction lifetime</a> rules. If this takes longer than the specified <var>timeout</var> then
|
|
a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-timeouterror">TimeoutError</a> should be thrown.
|
|
<p class="note">
|
|
Because the asynchronous API always passes in a <var>timeout</var> of infinite, only the synchronous
|
|
API will ever time out.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
If these steps are running synchronously, the implementation <em title="must" class="rfc2119">must</em> synchronously call <var>callback</var>
|
|
with a single parameter which is the <a class="internalDFN" href="#dfn-transaction">transaction</a>. If an exception is thrown and not caught within the
|
|
scope of the callback, the implementation <em title="must" class="rfc2119">must</em> abort the <a class="internalDFN" href="#dfn-transaction">transaction</a> by following the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for
|
|
aborting a transaction</a>, abort this algorithm without taking any further steps, and re-throw the exception.
|
|
</li>
|
|
<li>
|
|
If these steps are running synchronously, the implementation <em title="must" class="rfc2119">must</em> commit the transaction synchrnously.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="steps-for-committing-a-transaction" class="section">
|
|
<h3><span class="secno">4.3 </span>Steps for committing a transaction</h3>
|
|
<p>
|
|
When taking the <dfn id="dfn-steps-for-committing-a-transaction">steps for committing a <a class="internalDFN" href="#dfn-transaction">transaction</a></dfn> the implementation <em title="must" class="rfc2119">must</em>
|
|
execute the following algorithm. This algorithm takes one parameter, the <var>transaction</var> to commit.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
All the changes made to the <a class="internalDFN" href="#dfn-database">database</a> the transaction uses are written to the <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</li>
|
|
<li>
|
|
Queue up an operation to dispatch an event at <a class="internalDFN" href="#dfn-transaction">transaction</a>.
|
|
The event must use the <a><code>Event</code></a> interface and have its <code>type</code> set to <code>"complete"</code>.
|
|
The event does not bubble and is not cancelable. The
|
|
<a class="internalDFN" href="#dfn-propagation-path">propagation path</a> for the event is <var>transaction</var>'s <a class="internalDFN" href="#dfn-transaction-connection" title="transaction connection">connection</a> and
|
|
then <var>transaction</var>.
|
|
</li>
|
|
<li>
|
|
If an error occurs while committing the transaction, <a class="internalDFN" href="#dfn-fire-an-error-event">fire an error event</a>,
|
|
set the error attribute to a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-unknownerror">UnknownError</a>,
|
|
and then follow the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
<p class="note">
|
|
Even if the event is cancelled (by a call to <code>preventDefault</code>), follow the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="steps-for-aborting-a-transaction" class="section">
|
|
<h3><span class="secno">4.4 </span>Steps for aborting a transaction</h3>
|
|
<p>
|
|
When taking the <dfn id="dfn-steps-for-aborting-a-transaction">steps for aborting a <a class="internalDFN" href="#dfn-transaction">transaction</a></dfn> the implementation <em title="must" class="rfc2119">must</em>
|
|
execute the following algorithm. This algorithm takes two parameter, the <var>transaction</var> to abort
|
|
and an <var>error</var> object.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
All the changes made to the <a class="internalDFN" href="#dfn-database">database</a> the transaction uses are reverted. For VERSION_CHANGE
|
|
transactions this includes changes to the set of <a class="internalDFN" href="#dfn-object-store">object store</a>s and <a class="internalDFN" href="#dfn-index">index</a>es, as well
|
|
as the change to the <a class="internalDFN" href="#dfn-version">version</a>.
|
|
</li>
|
|
<li>
|
|
If the transaction's <a class="internalDFN" href="#dfn-request-list">request list</a> contain any <a class="internalDFN" href="#dfn-request">request</a>s whose <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag
|
|
is still false, abort the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> for each such request and queue
|
|
a task to perform the following steps:
|
|
<ol>
|
|
<li>
|
|
Set the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag on the <a class="internalDFN" href="#dfn-request">request</a> to true, set
|
|
<a class="internalDFN" href="#dfn-request-result" title="request result">result</a> of the <a class="internalDFN" href="#dfn-request">request</a> to <code>undefined</code>
|
|
and set the request's <code>error</code> atttribute to a <code>DOMError</code> with a type of <a class="internalDFN" href="#dfn-aborterror">AbortError</a>.
|
|
</li>
|
|
<li>
|
|
<a class="internalDFN" href="#dfn-fire-an-error-event">Fire an error event</a> at the <a class="internalDFN" href="#dfn-request">request</a>.
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
Queue up an operation to dispatch an event at <var>transaction</var>.
|
|
The event must use the <a><code>Event</code></a> interface and have its <code>type</code> set to <code>"abort"</code>.
|
|
The event does bubble but is not cancelable.
|
|
The <a class="internalDFN" href="#dfn-propagation-path">propagation path</a> for the event is <var>transaction</var>'s <a class="internalDFN" href="#dfn-transaction-connection" title="transaction connection">connection</a> and
|
|
then <var>transaction</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="steps-for-asynchronously-executing-a-request" class="section">
|
|
<h3><span class="secno">4.5 </span>Steps for asynchronously executing a <a class="internalDFN" href="#dfn-request">request</a></h3>
|
|
<p>
|
|
When taking the <dfn id="dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</dfn> the implementation <em title="must" class="rfc2119">must</em> run the
|
|
following algorithm. The algorithm takes a <var>source</var> object and an <var>operation</var> to
|
|
perform on a database.
|
|
</p>
|
|
<p>
|
|
These steps can be aborted at any point if the <a class="internalDFN" href="#dfn-transaction">transaction</a> the created <a class="internalDFN" href="#dfn-request">request</a> belongs
|
|
to is <a title="transaction abort">aborted</a> using the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Set <var>transaction</var> to the <a class="internalDFN" href="#dfn-transaction">transaction</a> associated with <var>source</var>.
|
|
</li>
|
|
<li>
|
|
If <var>transaction</var> is not <a class="internalDFN" href="#dfn-active">active</a> throw a <code>DOMException</code> of type <a class="internalDFN" href="#dfn-transactioninactiveerror">TransactionInactiveError</a>.
|
|
</li>
|
|
<li>
|
|
Create an <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> object and set <var>request</var> to this object. Set <var>request</var>'s
|
|
<a class="internalDFN" href="#dfn-request-source" title="request source">source</a> to <var>source</var> and add <var>request</var> to the end of the
|
|
<a class="internalDFN" href="#dfn-request-list" title="request list">list</a> of <a class="internalDFN" href="#dfn-request">request</a>s in <var>transaction</var>.
|
|
Return this object and queue up the execution of the remaining steps in this algorithm.
|
|
<p class="note">
|
|
Cursors override this step to reuse an existing <a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a>. However they still put the
|
|
<a class="idlType" href="#idl-def-IDBRequest"><code>IDBRequest</code></a> at the end of the list of <a class="internalDFN" href="#dfn-request">request</a>s in <var>transaction</var>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
Wait until all previously added <a>requests</a><a> in <var>transaction</var> have their
|
|
</a><a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag set to true.
|
|
</li>
|
|
<li>
|
|
Perform <var>operation</var>.
|
|
</li>
|
|
<li>
|
|
If performing <var>operation</var> succeeded then set the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag
|
|
on the <var>request</var> to true, set <a class="internalDFN" href="#dfn-request-result" title="request result">result</a> of the <var>request</var>
|
|
to the result of the request and set the <code>error</code> attribute of the <var>request</var> to <code>undefined</code>.
|
|
Finally <a class="internalDFN" href="#dfn-fire-a-success-event">fire a success event</a> at <var>request</var>.
|
|
</li>
|
|
<li>
|
|
If performing <var>operation</var> failed then revert all changes made by <var>operation</var>,
|
|
set the <a class="internalDFN" href="#dfn-request-done" title="request done">done</a> flag on the <var>request</var> to true,
|
|
set <a class="internalDFN" href="#dfn-request-result" title="request result">result</a> of the <var>request</var>
|
|
to <code>undefined</code> and set the <code>error</code> attribute on the <var>request</var>
|
|
to the a <code>DOMError</code> with the same error type of the <var>operation</var> that failed.
|
|
Finally <a class="internalDFN" href="#dfn-fire-an-error-event">fire an error event</a> at <var>request</var>.
|
|
<div class="note">
|
|
This only reverts the changes done by this request, not any other changes made by the transaction.
|
|
</div>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="steps-for-synchronously-executing-a-request" class="section">
|
|
<h3><span class="secno">4.6 </span>Steps for synchronously executing a <a class="internalDFN" href="#dfn-request">request</a></h3>
|
|
<p>
|
|
When taking the <dfn id="dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</dfn> the implementation <em title="must" class="rfc2119">must</em> run the
|
|
following algorithm. The algorithm takes a <var>source</var> object and an <var>operation</var> to
|
|
perform on a database.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If the <a class="internalDFN" href="#dfn-transaction">transaction</a> associated with <var>source</var> is not <a class="internalDFN" href="#dfn-active">active</a> throw a
|
|
<code>DOMException</code> of type <a class="internalDFN" href="#dfn-transactioninactiveerror">TransactionInactiveError</a>.
|
|
</li>
|
|
<li>
|
|
Perform <var>operation</var>.
|
|
</li>
|
|
<li>
|
|
If performing <var>operation</var> succeeded then return the result of the operation.
|
|
</li>
|
|
<li>
|
|
If performing <var>operation</var> failed, then throw a <code>DOMException</code> with the type
|
|
of error from the <var>operation</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="steps-for-extracting-a-key-from-a-value-using-a-key-path" class="section">
|
|
<h3><span class="secno">4.7 </span>Steps for extracting a key from a value using a <a class="internalDFN" href="#dfn-key-path">key path</a></h3>
|
|
<p>
|
|
When taking the <dfn id="dfn-steps-for-extracting-a-key-from-a-value-using-a-key-path">steps for extracting a key from a value using a key path</dfn>, the implementation
|
|
<em title="must" class="rfc2119">must</em> run the following algorithm. The algorithm takes a <a class="internalDFN" href="#dfn-key-path">key path</a> named <var>keyPath</var> and a
|
|
<a class="internalDFN" href="#dfn-value-1">value</a> named <var>value</var> and in some cases returns a <a class="internalDFN" href="#dfn-key-1">key</a> which may or may not be a
|
|
<a class="internalDFN" href="#dfn-valid-key">valid key</a>.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If <var>keyPath</var> is the empty string, return <var>value</var> and skip the remaining steps.
|
|
</li>
|
|
<li>
|
|
Let <var>remainingKeypath</var> be <var>keyPath</var> and <var>object</var> be <var>value</var>.
|
|
</li>
|
|
<li>
|
|
If <var>remainingKeypath</var> has a period in it, assign <var>remainingKeypath</var> to be
|
|
everything after the first period and assign <var>attribute</var> to be everything before that
|
|
first period. Otherwise, assign<var>attribute</var>
|
|
to be <var>remainingKeypath</var> and assign <var>remainingKeypath</var> to be null.
|
|
</li>
|
|
<li>
|
|
If <var>object</var> does not have an attribute named <var>attribute</var>, then skip the rest of
|
|
these steps and no value is returned.
|
|
</li>
|
|
<li>
|
|
Assign <var>object</var> to be the value of the attribute named <var>attribute</var> on <var>object</var>.
|
|
</li>
|
|
<li>
|
|
If <var>remainingKeypath</var> is not null, go to step 3.
|
|
</li>
|
|
<li>
|
|
Return <var>object</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="version_change-transaction-steps" class="section">
|
|
<h3><span class="secno">4.8 </span>VERSION_CHANGE transaction steps</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-running-a-version_change-transaction">steps for running a <code>VERSION_CHANGE</code> transaction</dfn> are
|
|
as follows. This algorithm takes two required parameters - a <var>connection</var> object which is used
|
|
to update the <a class="internalDFN" href="#dfn-database">database</a> a new <var>version</var> to be set for the <a class="internalDFN" href="#dfn-database">database</a>.
|
|
The algorithm also takes two optional arguments, a <var>request</var> which represents a <a class="internalDFN" href="#dfn-request">request</a>
|
|
used when the asynchronous API is used, or a <var>upgrade callback</var> which
|
|
represents the callback used when the synchronous API is used.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Let <var>openDatabases</var> be the set of all <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> and <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a>
|
|
objects, except <var>connection</var>, connected to the same <a class="internalDFN" href="#dfn-database">database</a> as <var>connection</var>.
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fire a <code>versionchange</code> event at each object in <var>openDatabases</var> that is open. The event <em title="must not" class="rfc2119">must not</em>
|
|
be fired on objects which has the <code>closePending</code> flag set. The event <em title="must" class="rfc2119">must</em> use the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> interface and have the
|
|
<a href="#widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code></a> property set to <var>db</var>'s
|
|
<a class="internalDFN" href="#dfn-version">version</a> and have the <a href="#widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code></a>
|
|
property set to <var>version</var>.
|
|
This event <em title="must not" class="rfc2119">must not</em> bubble or be cancelable. The propagation path for the event is just the <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a>
|
|
object itself.
|
|
</p>
|
|
<p class="note">
|
|
Firing this event might cause one or more of the other objects in <var>openDatabases</var> to be closed, in which case
|
|
the <code>versionchange</code> event <em title="must not" class="rfc2119">must not</em> be fired at those objects if that hasn't yet been done.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
If running asynchronously and any of the <a class="internalDFN" href="#dfn-connection">connection</a>s in <var>openDatabases</var> are still not closed,
|
|
queue up a <code>blocked</code> event for the <var>request</var>. The event <em title="must" class="rfc2119">must</em> use the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> interface and have the
|
|
<a href="#widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code></a> property set to <var>db</var>'s
|
|
<a class="internalDFN" href="#dfn-version">version</a> and have the <a href="#widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code></a>
|
|
property set to <var>version</var>.
|
|
This event <em title="must not" class="rfc2119">must not</em> bubble or be cancelable. The propagation path for the event is just <var>request</var>.
|
|
</p>
|
|
</li>
|
|
<li id="VERSION_CHANGE-close-block">
|
|
Wait until either all objects in <var>openDatabases</var> are <a class="internalDFN" href="#dfn-database-close-1" title="database close">closed</a> and all of
|
|
their transactions are <a title="transaction finish">finished</a>.
|
|
<p class="issue">If .close() is called immediately but a <a class="internalDFN" href="#dfn-transaction">transaction</a> associated with the <var>connection</var>
|
|
keeps running for a "long time", should we also fire a <code>blocked</code> event?</p>
|
|
<p class="issue">If, while we're waiting here, someone calls open with a version number higher than <var>version</var>,
|
|
we should probably let that upgrade run first and bail here if it was successful</p>
|
|
</li>
|
|
<li>
|
|
Create a new <a class="internalDFN" href="#dfn-transaction">transaction</a> with <a class="internalDFN" href="#dfn-mode">mode</a> set to VERSION_CHANGE and <var>connection</var> used as <a class="internalDFN" href="#dfn-connection">connection</a>.
|
|
The <a class="internalDFN" href="#dfn-scope">scope</a> of the transaction includes every <a class="internalDFN" href="#dfn-object-store">object store</a> in <var>connection</var>. Set its
|
|
<a class="internalDFN" href="#dfn-active">active</a> flag to false. Let <var>transaction</var> represent this transaction.
|
|
</li>
|
|
<li>
|
|
Start <var>transaction</var>. Note that until this <a class="internalDFN" href="#dfn-transaction">transaction</a> is finished,
|
|
no other <a class="internalDFN" href="#dfn-connection">connection</a>s can be opened to the same <a class="internalDFN" href="#dfn-database">database</a>.
|
|
</li>
|
|
<li>
|
|
Let <var>old version</var> be <var>database</var>'s <a class="internalDFN" href="#dfn-version">version</a>.
|
|
</li>
|
|
<li>
|
|
Set the version of <var>database</var> to <var>version</var>. This change is considered part of the
|
|
<a class="internalDFN" href="#dfn-transaction">transaction</a>, and so if the transaction is <a class="internalDFN" href="#dfn-abort">abort</a>ed, this change is reverted.
|
|
If the VERSION_CHANGE <a class="internalDFN" href="#dfn-transaction">transaction</a> fails to commit set the <var>version</var> attribute on the database to <code>undefined</code>.
|
|
</li>
|
|
<li>
|
|
If running asynchronously, schedule a task to run the following steps:
|
|
<ol>
|
|
<li>
|
|
Set the <a><code>result</code></a> property of <var>request</var> to <var>connection</var>.
|
|
</li>
|
|
<li>
|
|
Set the <code>transaction</code> property of <var>request</var> to <var>transaction</var>.
|
|
</li>
|
|
<li>
|
|
Fire a <a><code>upgradeneeded</code></a> event targeted at <var>request</var>. The event <em title="must" class="rfc2119">must</em> use the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> interface and have the
|
|
<a href="#widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code></a> property set to <var>old version</var>
|
|
and have the <a href="#widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code></a>
|
|
property set to <var>version</var>.
|
|
The <a class="idlType" href="#widl-IDBRequest-readyState"><code>readyState</code></a>
|
|
on the <a class="internalDFN" href="#dfn-request">request</a> is set to <a><code>DONE</code></a>.
|
|
</li>
|
|
<li>
|
|
If an exception was propagated out from any event
|
|
handler while dispatching the event in the previous step, abort
|
|
the transaction by following the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
If running synchronously, call <var>upgrade callback</var> and pass it <var>transaction</var> as the first argument
|
|
and <var>old version</var> the second argument.
|
|
</li>
|
|
<li>
|
|
Follow the normal steps for executing a <a class="internalDFN" href="#dfn-transaction"><code>transaction</code></a> and let the <a class="internalDFN" href="#dfn-transaction"><code>transaction</code></a>
|
|
finish normally.
|
|
</li>
|
|
<li>
|
|
When the transaction is finished, if these steps are run asynchronously, immediately set <var>request</var>'s
|
|
<code>transaction</code> property to <code>null</code>. This <em title="must" class="rfc2119">must</em> be done in the same task as the task firing the
|
|
<code>complete</code> or <code>abort</code> event, but after those events has been fired.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="database-closing-steps" class="section">
|
|
<h3><span class="secno">4.9 </span>Database closing steps</h3>
|
|
<p>The <dfn id="dfn-steps-for-closing-a-database-connection">steps for closing a database connection</dfn> are as follows. These steps take one argument, a <var>connection</var> object.
|
|
</p><ol>
|
|
<li>
|
|
Set the internal <a class="internalDFN" href="#dfn-closepending"><code>closePending</code></a> flag of <var>connection</var> to true.
|
|
</li>
|
|
<li>
|
|
Wait for all transactions <a class="internalDFN" href="#dfn-transaction-create" title="transaction create">created</a> using <var>connection</var> to complete.
|
|
Once they are complete, <var>connection</var> is <dfn id="dfn-database-close-1" title="database close">closed</dfn>.
|
|
</li>
|
|
</ol>
|
|
<p class="note">
|
|
Once the <a class="internalDFN" href="#dfn-closepending"><code>closePending</code></a> flag has ben set to true no new transactions can be
|
|
<a class="internalDFN" href="#dfn-transaction-create" title="transaction create">created</a> using <var>connection</var>. All functions that
|
|
<a class="internalDFN" href="#dfn-transaction-create" title="transaction create">create</a> transactions first check the the <a class="internalDFN" href="#dfn-closepending">closePending</a> flag first and
|
|
throw an exception if it is true.
|
|
</p>
|
|
<p class="note">
|
|
Once the <a class="internalDFN" href="#dfn-connection">connection</a> is closed, this can unblock the <a class="internalDFN" href="#dfn-steps-for-running-a-version_change-transaction">steps for running a <code>VERSION_CHANGE</code>
|
|
transaction</a>, and the <a class="internalDFN" href="#dfn-steps-for-deleting-a-database">steps for deleting a database</a>, which <a href="#delete-close-block">both</a>
|
|
<a href="#VERSION_CHANGE-close-block">wait</a> for <a class="internalDFN" href="#dfn-connection">connection</a>s to a given <a class="internalDFN" href="#dfn-database">database</a> to be closed
|
|
before continuing.
|
|
</p>
|
|
</div>
|
|
<div id="database-deletion-steps" class="section">
|
|
<h3><span class="secno">4.10 </span>Database deletion steps</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-deleting-a-database">steps for deleting a <a class="internalDFN" href="#dfn-database">database</a></dfn> are as follows. The algorithm in these steps
|
|
take three arguments. An <var>origin</var> which requested the <a class="internalDFN" href="#dfn-database">database</a> to be deleted,
|
|
a database <var>name</var>. It also optionally takes a <var>request</var> which represents
|
|
a <a class="internalDFN" href="#dfn-request">request</a> used when deleting the database is done using an asynchronous API.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If there is already a database with the given name from the origin <var>origin</var>, then
|
|
let <var>db</var> be that database.
|
|
</li>
|
|
<li>
|
|
If no database was found, then these steps are considered successful. Abort these steps.
|
|
</li>
|
|
<li>
|
|
Set <var>db</var>'s <a class="internalDFN" href="#dfn-delete-pending">delete pending</a> flag to true.
|
|
</li>
|
|
<li>
|
|
Let <var>openDatabases</var> be the set of all <a class="idlType" href="#idl-def-IDBDatabase"><code>IDBDatabase</code></a> and <a class="idlType" href="#idl-def-IDBDatabaseSync"><code>IDBDatabaseSync</code></a>
|
|
objects connected to <var>db</var>.
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Fire a <code>versionchange</code> event at each object in <var>openDatabases</var> that is open. The event <em title="must not" class="rfc2119">must not</em>
|
|
be fired on objects which has the <code>closePending</code> flag set. The event <em title="must" class="rfc2119">must</em> use the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> interface and have the
|
|
<a href="#widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code></a> property set to <var>db</var>'s
|
|
<a class="internalDFN" href="#dfn-version">version</a> and have the <a href="#widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code></a>
|
|
property set to <code>null</code>.
|
|
This event <em title="must not" class="rfc2119">must not</em> bubble or be cancelable.
|
|
</p>
|
|
<p class="note">
|
|
Firing this event might cause one or more of the other objects in <var>openDatabases</var> to be closed, in which case
|
|
the <code>versionchange</code> event <em title="must not" class="rfc2119">must not</em> be fired at those objects if that hasn't yet been done.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
If any of the <a class="internalDFN" href="#dfn-connection">connection</a>s in <var>openDatabases</var> are still not closed, and <var>request</var> was provided,
|
|
fire a <code>blocked</code> event at <var>request</var>. The event <em title="must" class="rfc2119">must</em> use the
|
|
<a class="idlType" href="#idl-def-IDBVersionChangeEvent"><code>IDBVersionChangeEvent</code></a> interface and have the
|
|
<a href="#widl-IDBVersionChangeEvent-oldVersion"><code>oldVersion</code></a> property set to <var>db</var>'s
|
|
<a class="internalDFN" href="#dfn-version">version</a> and have the <a href="#widl-IDBVersionChangeEvent-newVersion"><code>newVersion</code></a>
|
|
property set to <code>null</code>.
|
|
This event <em title="must not" class="rfc2119">must not</em> bubble or be cancelable.
|
|
</p>
|
|
</li>
|
|
<li id="delete-close-block">
|
|
Wait until all objects in <var>openDatabases</var> are <a class="internalDFN" href="#dfn-database-close-1" title="database close">closed</a> and all of
|
|
their transactions are <a title="transaction finish">finished</a>.
|
|
<p class="issue">Should we allow <code>blocked</code> to be fired here too, if waiting takes "too long"?</p>
|
|
</li>
|
|
<li>
|
|
Delete <var>db</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="fire-a-success-event" class="section">
|
|
<h3><span class="secno">4.11 </span>Fire a success event</h3>
|
|
<p>
|
|
To <dfn id="dfn-fire-a-success-event">fire a success event</dfn> at a <a class="internalDFN" href="#dfn-request">request</a>,
|
|
the implementation <em title="must" class="rfc2119">must</em> run the following steps:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Set <var>transaction</var> to the <a class="internalDFN" href="#dfn-transaction">transaction</a> associated with the <a class="internalDFN" href="#dfn-request-source" title="request source">source</a>.
|
|
</li>
|
|
<li>
|
|
Set the <a class="internalDFN" href="#dfn-active">active</a> flag of <var>transaction</var> to true.
|
|
</li>
|
|
<li>
|
|
Dispatch an event at <a class="internalDFN" href="#dfn-request">request</a>. The event must use
|
|
the <a><code>Event</code></a> interface and have its <code>type</code> set to <code>"success"</code>.
|
|
The event does not bubble or be cancelable. The
|
|
<a class="internalDFN" href="#dfn-propagation-path">propagation path</a> for the event is <var>transaction</var>'s <a class="internalDFN" href="#dfn-transaction-connection" title="transaction connection">connection</a>,
|
|
then <var>transaction</var> and finally <var>request</var>.
|
|
</li>
|
|
<li>
|
|
Set the <a class="internalDFN" href="#dfn-active">active</a> flag of <var>transaction</var> to false.
|
|
</li>
|
|
<li>
|
|
If an exception was propagated out from any event handler while dispatching the event in step 3,
|
|
abort the transaction by following the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div id="fire-an-error-event" class="section">
|
|
<h3><span class="secno">4.12 </span>Fire an error event</h3>
|
|
<p>
|
|
To <dfn id="dfn-fire-an-error-event" title="fire an error event">fire an error event</dfn> at a <a class="internalDFN" href="#dfn-request">request</a>,
|
|
the implementation <em title="must" class="rfc2119">must</em> run the following steps:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Set <var>transaction</var> to the <a class="internalDFN" href="#dfn-transaction">transaction</a> associated with the <a class="internalDFN" href="#dfn-request-source" title="request source">source</a>.
|
|
</li>
|
|
<li>
|
|
Set the <a class="internalDFN" href="#dfn-active">active</a> flag of <var>transaction</var> to true.
|
|
</li>
|
|
<li>
|
|
Dispatch an event at <a class="internalDFN" href="#dfn-request">request</a>. The event must use
|
|
the <a><code>Event</code></a> interface and have its <code>type</code> set to <code>"error"</code>.
|
|
The event does bubble and is cancelable. The
|
|
<a class="internalDFN" href="#dfn-propagation-path">propagation path</a> for the event is <var>transaction</var>'s <a class="internalDFN" href="#dfn-transaction-connection" title="transaction connection">connection</a>,
|
|
then <var>transaction</var> and finally <var>request</var>. The event's <a class="internalDFN" href="#dfn-default-action">default action</a> is to abort the
|
|
<var>transaction</var> by running <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</li>
|
|
<li>
|
|
Set the <a class="internalDFN" href="#dfn-active">active</a> flag of <var>transaction</var> to false.
|
|
</li>
|
|
<li>
|
|
If an exception was propagated out from any event handler while dispatching the event in step 3,
|
|
abort the transaction by following the <a class="internalDFN" href="#dfn-steps-for-aborting-a-transaction">steps for aborting a transaction</a>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="database-operations">
|
|
<!--OddPage--><h2><span class="secno">5. </span>Database operations</h2>
|
|
<p>
|
|
This section describes various operations done on the data in <a class="internalDFN" href="#dfn-object-store">object store</a>s and <a class="internalDFN" href="#dfn-index">index</a>es
|
|
in a <a class="internalDFN" href="#dfn-database">database</a>. These operations are run by the <a class="internalDFN" href="#dfn-steps-for-asynchronously-executing-a-request">steps for asynchronously executing a request</a> and
|
|
the <a class="internalDFN" href="#dfn-steps-for-synchronously-executing-a-request">steps for synchronously executing a request</a>.
|
|
</p>
|
|
<div id="object-store-storage-operation" class="section">
|
|
<h3><span class="secno">5.1 </span>Object Store Storage Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-storing-a-record-into-an-object-store">steps for storing a record into an object store</dfn> are as follows.
|
|
The algorithm run by these steps takes four parameters: an object store <var>store</var>,
|
|
a <var>value</var>, an optional <var>key</var>, and a <var>no-overwrite flag</var>.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If <var>store</var> does use <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a> and <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluting</a>
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path"><var>store</var>'s key path</a> on <var>value</var> does yield
|
|
a value, then set <var>key</var> to that result.
|
|
</li>
|
|
<li>
|
|
If <var>store</var> uses a <a class="internalDFN" href="#dfn-key-generator">key generator</a> and <var>key</var> is undefined, set
|
|
<var>key</var> to the next generated key. If <var>store</var> also uses <a class="internalDFN" href="#dfn-in-line-keys">in-line keys</a>,
|
|
then set the property in <var>value</var> pointed to by <var>store</var>'s
|
|
<a class="internalDFN" href="#dfn-object-store-key-path" title="object store key path">key path</a> to the new value for <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>store</var> uses a <a class="internalDFN" href="#dfn-key-generator">key generator</a>, this <a class="internalDFN" href="#dfn-key-generator">key generator</a> was not used to generate a value
|
|
for <var>key</var> in the previous step, <var>key</var> is defined to a <code>long</code>
|
|
or a <code>float</code> and this number is larger than, or equal to, the next key that <var>store</var>'s
|
|
<a class="internalDFN" href="#dfn-key-generator">key generator</a> would generate, change <var>store</var>'s <a class="internalDFN" href="#dfn-key-generator">key generator</a> such that the next
|
|
key it generates is the lowest integer larger than <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If the no-overwrite flag was passed to these steps and is set, and
|
|
a <a class="internalDFN" href="#dfn-record">record</a> already exists in <var>store</var> with its key <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>, then
|
|
terminate these steps and set the <code>error</code> attribute to
|
|
a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-constrainterror">ConstraintError</a>
|
|
and abort this algorithm without taking any further steps.
|
|
</li>
|
|
<li>
|
|
If a <a class="internalDFN" href="#dfn-record">record</a> already exists in <var>store</var> with its key <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>, then
|
|
remove the <a class="internalDFN" href="#dfn-record">record</a> from <a>store</a> using the <a class="internalDFN" href="#dfn-steps-for-deleting-records-from-an-object-store">steps for deleting records from an object store</a>.
|
|
</li>
|
|
<li>
|
|
Store a record in <var>store</var> containing <var>key</var> as its key and <var>object</var> as its
|
|
value. The record is stored in the the object store's <a title="objec store record list">list</a> such
|
|
that the list is sorted according key of the records in ascending order.
|
|
</li>
|
|
<li>
|
|
If there are any <a class="internalDFN" href="#dfn-index">index</a>es which <a class="internalDFN" href="#dfn-referenced" title="referenced">reference</a> <var>store</var>, perform the
|
|
following sub steps on each such index.
|
|
<ol>
|
|
<li>
|
|
Set <var>index</var> to the index.
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is a string, then
|
|
<a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluate</a> it on
|
|
<var>value</var>. If this does not yield a value don't take any further actions for this index.
|
|
Otherwise set the result to <var>index key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> is an <code>Array</code>, then set
|
|
<var>index key</var> to a newly created empty <code>Array</code>. For each item in
|
|
<var>index</var>'s <a class="internalDFN" href="#dfn-index-key-path" title="index key path">key path</a> <a class="internalDFN" href="#dfn-evaluate-key-path" title="evaluate key path">evaluate</a>
|
|
the item on <var>value</var>. If this does not yield a value don't take any further actions for this index.
|
|
Otherwise add the value to the end of the <var>index key</var> <code>Array</code>.
|
|
</li>
|
|
<li>
|
|
<div class="note">
|
|
The places invoking these steps ensures that <var>index key</var> is always a <a class="internalDFN" href="#dfn-valid-key">valid key</a> by the time
|
|
we get to this step.
|
|
</div>
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is false, or if <var>index key</var> is not an <code>Array</code>,
|
|
and if <var>index</var> already contains a <a class="internalDFN" href="#dfn-record">record</a> with <a class="internalDFN" href="#dfn-key-1">key</a> <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>index key</var>,
|
|
and <var>index</var> has it's <a class="internalDFN" href="#dfn-unique">unique</a> flag set to true, then
|
|
set the <code>error</code> attribute to a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-constrainterror">ConstraintError</a>
|
|
and abort this algorithm without taking any further steps.
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is true and <var>index key</var> is an <code>Array</code>,
|
|
and if <var>index</var> already contains a <a class="internalDFN" href="#dfn-record">record</a> with <a class="internalDFN" href="#dfn-key-1">key</a> <a class="internalDFN" href="#dfn-equal-to">equal to</a> any of the
|
|
values in <var>index key</var>, and <var>index</var> has it's <a class="internalDFN" href="#dfn-unique">unique</a> flag set to true, then set
|
|
set the <code>error</code> attribute to a <code>DOMError</code> of type <a class="internalDFN" href="#dfn-constrainterror">ConstraintError</a>
|
|
and abort this algorithm without taking any further steps.
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is false, or if <var>index key</var> is not an <code>Array</code>,
|
|
then store a record in <var>index</var> containig <var>index key</var> as its key and <var>key</var> as its
|
|
value. The record is stored in <var>index</var>'s <a class="internalDFN" href="#dfn-index-record-list" title="index record list">list of records</a> such
|
|
that the list is sorted primarily on the records keys, and secondarily on the records values, in ascending
|
|
order.
|
|
</li>
|
|
<li>
|
|
If <var>index</var>'s <a class="internalDFN" href="#dfn-multientry">multientry</a> flag is true and <var>index key</var> is an <code>Array</code>,
|
|
then for each item in <var>index key</var> store a record in <var>index</var> containig
|
|
the items value as its key and <var>key</var> as its value. The records are stored in <var>index</var>'s
|
|
<a class="internalDFN" href="#dfn-index-record-list" title="index record list">list of records</a> such that the list is sorted primarily on the records keys,
|
|
and secondarily on the records values, in ascending order.
|
|
<div class="note">
|
|
Note that it is legal for the <code>Array</code> to have length 0, in this case no records are added to
|
|
the index.
|
|
</div>
|
|
<div class="note">
|
|
If any of the items in the <code>Array</code> are themselves an <code>Array</code>, then the inner
|
|
<code>Array</code> is used as a key for that entry. In other words, <code>Array</code>s are not recursively
|
|
"unpacked" to produce multiple rows. Only the outer-most <code>Array</code> is.
|
|
</div>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
The result of this algorithm is <var>key</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="object-store-retrieval-operation" class="section">
|
|
<h3><span class="secno">5.2 </span>Object Store Retrieval Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-retrieving-a-value-from-an-object-store">steps for retrieving a value from an object store</dfn> are
|
|
as follows. These steps <em title="must" class="rfc2119">must</em> be run with two parameters - the record
|
|
key and the <a class="internalDFN" href="#dfn-object-store">object store</a>.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Let <var>key</var> be the key and <var>store</var> be the <a class="internalDFN" href="#dfn-object-store">object
|
|
store</a> passed to these steps.
|
|
</li>
|
|
<li>
|
|
If <var>key</var> is not a <a class="internalDFN" href="#dfn-key-range">key range</a> then retreive the <a class="internalDFN" href="#dfn-record">record</a>
|
|
with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a class="internalDFN" href="#dfn-key-range">key range</a>, then
|
|
retreive the first <a class="internalDFN" href="#dfn-record">record</a> from <var>store</var> whose key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If no record was found, the result of this algorithm is <code>undefined</code>.
|
|
</li>
|
|
<li>
|
|
The result of this algorithm is a new <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the value in the found record.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="index-referenced-value-retrieval-operation" class="section">
|
|
<h3><span class="secno">5.3 </span>Index Referenced Value Retrieval Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-retrieving-a-referenced-value-from-an-index">steps for retrieving a referenced value from an index</dfn> are
|
|
as follows. These steps <em title="must" class="rfc2119">must</em> be run with two parameters - the record
|
|
key and the <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Let <var>key</var> be the key and <var>index</var> be the <a class="internalDFN" href="#dfn-index">index</a>
|
|
passed to these steps.
|
|
</li>
|
|
<li>
|
|
If <var>key</var> is not a <a class="internalDFN" href="#dfn-key-range">key range</a> then find the first <a class="internalDFN" href="#dfn-record">record</a>
|
|
with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a class="internalDFN" href="#dfn-key-range">key range</a>, then
|
|
find the first <a class="internalDFN" href="#dfn-record">record</a> from <var>index</var> whose key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If no record was found, the result of this algorithm is <code>undefined</code>.
|
|
</li>
|
|
<li>
|
|
Otherwise, the result of the operation is a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of the <a class="internalDFN" href="#dfn-referenced-value">referenced value</a> of the found record.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="index-value-retrieval-operation" class="section">
|
|
<h3><span class="secno">5.4 </span>Index Value Retrieval Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-retrieving-a-value-from-an-index">steps for retrieving a value from an index</dfn> are
|
|
as follows. These steps <em title="must" class="rfc2119">must</em> be run with two parameters - the record
|
|
key and the <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Let <var>key</var> be the key and <var>index</var> be the <a class="internalDFN" href="#dfn-index">index</a>
|
|
passed to these steps.
|
|
</li>
|
|
<li>
|
|
If <var>key</var> is not a <a class="internalDFN" href="#dfn-key-range">key range</a> then find the first <a class="internalDFN" href="#dfn-record">record</a>
|
|
with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a class="internalDFN" href="#dfn-key-range">key range</a>, then
|
|
find the first <a class="internalDFN" href="#dfn-record">record</a> from <var>index</var> whose key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If no record was found, the result of this algorithm is <code>undefined</code>.
|
|
</li>
|
|
<li>
|
|
If a record was found, the result of this algorithm is the <a class="internalDFN" href="#dfn-value-1">value</a> of the found <a class="internalDFN" href="#dfn-record">record</a>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="object-store-deletion-operation" class="section">
|
|
<h3><span class="secno">5.5 </span>Object Store Deletion Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-deleting-records-from-an-object-store">steps for deleting records from an object store</dfn> are as follows.
|
|
The algorithm run by these steps takes two parameters: an object store <var>store</var> and
|
|
a <var>key</var>.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
If the <var>key</var> parameter is a <a class="internalDFN" href="#dfn-key-range">key range</a> then let <var>range</var> be that <a class="internalDFN" href="#dfn-key-range">key range</a>.
|
|
Otherwise, let <var>range</var> be a <a class="internalDFN" href="#dfn-key-range">key range</a> which containing only <var>key</var>.
|
|
</li>
|
|
<li>
|
|
Remove all records, if any, from <var>store</var> with key <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>.
|
|
</li>
|
|
<li>
|
|
In all <a class="internalDFN" href="#dfn-index">index</a>es which <a class="internalDFN" href="#dfn-referenced" title="referenced">reference</a> <var>store</var>, remove all
|
|
<a>records</a> whose value is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>, if any such records exist.
|
|
</li>
|
|
<li>
|
|
The result of this algorithm is <code>undefined</code>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="object-store-clear-operation" class="section">
|
|
<h3><span class="secno">5.6 </span>Object Store Clear Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-clearing-an-object-store">steps for clearing an object store</dfn> are as follows.
|
|
The algorithm run by these steps takes one parameter: an object store <var>store</var>.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Remove all records from <var>store</var>.
|
|
</li>
|
|
<li>
|
|
In all <a class="internalDFN" href="#dfn-index">index</a>es which <a class="internalDFN" href="#dfn-referenced" title="referenced">reference</a> <var>store</var>, remove all
|
|
<a>records</a>.
|
|
</li>
|
|
<li>
|
|
The result of this algorithm is <code>undefined</code>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div id="cursor-iteration-operation" class="section">
|
|
<h3><span class="secno">5.7 </span>Cursor Iteration Operation</h3>
|
|
<p>
|
|
The <dfn id="dfn-steps-for-iterating-a-cursor">steps for iterating a cursor</dfn> are as follows.
|
|
The algorithm run by these steps takes two parameters: a <var>cursor</var> and optional
|
|
<var>key</var> to iterate to.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Let <var>source</var> be <var>cursor</var>'s <a class="internalDFN" href="#dfn-cursor-source" title="cursor source">source</a>, let
|
|
<var>records</var> be list of <a>records</a> in <var>source</var>, let <var>direction</var>
|
|
be <var>cursor</var>'s <a class="internalDFN" href="#dfn-direction">direction</a>, let <var>position</var> be <var>cursor</var>'s
|
|
<a class="internalDFN" href="#dfn-position">position</a>, let <var>object store position</var> be <var>cursor</var>'s <a class="internalDFN" href="#dfn-object-store-position">object store position</a>
|
|
and let <var>range</var> be <var>cursor</var>'s <a class="internalDFN" href="#dfn-range">range</a>.
|
|
<p class="note">
|
|
<var>source</var> is always an <a class="internalDFN" href="#dfn-object-store">object store</a> or an <a class="internalDFN" href="#dfn-index">index</a>.
|
|
</p>
|
|
<p class="note">
|
|
<var>records</var> is always sorted in ascending <a class="internalDFN" href="#dfn-key-1">key</a> order. In the case of
|
|
<var>source</var> being an <a class="internalDFN" href="#dfn-index">index</a>, <var>records</var> is secondarily sorted in ascending
|
|
<a class="internalDFN" href="#dfn-value-1">value</a> order.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
If <var>direction</var> is NEXT, let <var>found record</var> be the first record in <var>records</var> which
|
|
satisfy all of the following requirements:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <var>key</var> is defined, the record's key is <a class="internalDFN" href="#dfn-greater-than">greater than</a> or <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, and <var>source</var> is an <a class="internalDFN" href="#dfn-object-store">object store</a>, the record's
|
|
key is <a class="internalDFN" href="#dfn-greater-than">greater than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, and <var>source</var> is an <a class="internalDFN" href="#dfn-index">index</a>, the record's
|
|
key is <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>position</var> and the record's value is <a class="internalDFN" href="#dfn-greater-than">greater than</a>
|
|
<var>object store position</var> or the record's key is <a class="internalDFN" href="#dfn-greater-than">greater than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>range</var> is defined, the record's key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If <var>direction</var> is NEXT_NO_DUPLICATE, let <var>found record</var> be the first record in <var>records</var> which
|
|
satisfy all of the following requirements:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <var>key</var> is defined, the record's key is <a class="internalDFN" href="#dfn-greater-than">greater than</a> or <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, the record's key is <a class="internalDFN" href="#dfn-greater-than">greater than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>range</var> is defined, the record's key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If <var>direction</var> is PREV, let <var>found record</var> be the last record in <var>records</var> which
|
|
satisfy all of the following requirements:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <var>key</var> is defined, the record's key is <a class="internalDFN" href="#dfn-less-than">less than</a> or <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, and <var>source</var> is an <a class="internalDFN" href="#dfn-object-store">object store</a>, the record's
|
|
key is <a class="internalDFN" href="#dfn-less-than">less than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, and <var>source</var> is an <a class="internalDFN" href="#dfn-index">index</a>, the record's
|
|
key is <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>position</var> and the record's value is <a class="internalDFN" href="#dfn-less-than">less than</a>
|
|
<var>object store position</var> or the record's key is <a class="internalDFN" href="#dfn-less-than">less than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>range</var> is defined, the record's key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If <var>direction</var> is PREV_NO_DUPLICATE, let <var>temp record</var> be the last record in
|
|
<var>records</var> which satisfy all of the following requirements:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <var>key</var> is defined, the record's key is <a class="internalDFN" href="#dfn-less-than">less than</a> or <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>key</var>.
|
|
</li>
|
|
<li>
|
|
If <var>position</var> is defined, the record's key is <a class="internalDFN" href="#dfn-less-than">less than</a> <var>position</var>.
|
|
</li>
|
|
<li>
|
|
If <var>range</var> is defined, the record's key is <a class="internalDFN" href="#dfn-in-a-key-range" title="in a key range">in</a> <var>range</var>.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If <var>temp record</var> is defined, let <var>found record</var> be the first record in <var>records</var>
|
|
whose key is <a class="internalDFN" href="#dfn-equal-to">equal to</a> <var>temp record</var>'s key.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
If <var>found record</var> is not defined, set <var>cursor</var>'s <a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> and <a>primary key</a> to
|
|
<code>undefined</code>.
|
|
If <var>cursor</var> implements <a class="idlType" href="#idl-def-IDBCursorWithValue"><code>IDBCursorWithValue</code></a> or <a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a>, then set
|
|
<var>cursor</var>'s <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a> to <code>undefined</code>.
|
|
The result of this algorithm is <code>null</code>. Abort these steps.
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Set <var>cursor</var>'s <a class="internalDFN" href="#dfn-position">position</a> to <var>found record</var>'s key. If <var>source</var> is an <a class="internalDFN" href="#dfn-index">index</a>,
|
|
set <var>cursor</var>'s <a class="internalDFN" href="#dfn-object-store-position">object store position</a> to <var>found record</var>'s value.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Set <var>cursor</var>'s <a class="internalDFN" href="#dfn-cursor-key" title="cursor key">key</a> to <var>found record</var>'s key.
|
|
</p>
|
|
<p>
|
|
If <var>cursor</var> implements <a class="idlType" href="#idl-def-IDBCursorWithValue"><code>IDBCursorWithValue</code></a> or <a class="idlType" href="#idl-def-IDBCursorWithValueSync"><code>IDBCursorWithValueSync</code></a>, then set
|
|
<var>cursor</var>'s <a class="internalDFN" href="#dfn-cursor-value" title="cursor value">value</a> to a <a class="internalDFN" href="#dfn-structured-clone">structured clone</a> of <var>found record</var>
|
|
<a class="internalDFN" href="#dfn-referenced-value">referenced value</a>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
Set <var>cursor</var>'s <a class="internalDFN" href="#dfn-got-value">got value</a> flag to true.
|
|
<p class="note">
|
|
Once data has been successfully read, schedule a task which when run will
|
|
set the <a class="internalDFN" href="#dfn-cursor" title="cursor">cursor's</a> value and <a class="internalDFN" href="#dfn-fire-a-success-event">fire a success event</a>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
The result of the algorithm is <var>cursor</var>.
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- database-api -->
|
|
|
|
|
|
<div id="privacy" class="section">
|
|
<!--OddPage--><h2><span class="secno">6. </span>Privacy</h2>
|
|
|
|
<div id="user-tracking" class="section">
|
|
<h3><span class="secno">6.1 </span>User tracking</h3>
|
|
|
|
<p>
|
|
A third-party host (or any object capable of getting content
|
|
distributed to multiple sites) could use a unique identifier
|
|
stored in its client-side database to track a user across multiple
|
|
sessions, building a profile of the user's activities. In conjunction
|
|
with a site that is aware of the user's real id object (for
|
|
example an e-commerce site that requires authenticated credentials),
|
|
this could allow oppressive groups to target individuals with
|
|
greater accuracy than in a world with purely anonymous Web usage.
|
|
</p>
|
|
|
|
<p>
|
|
There are a number of techniques that can be used to mitigate the
|
|
risk of user tracking:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt>Blocking third-party storage</dt>
|
|
<dd>
|
|
User agents <em title="may" class="rfc2119">may</em> restrict access to the database objects
|
|
to scripts originating at the domain of the top-level document of
|
|
the <span>browsing context</span>, for instance denying access to
|
|
the API for pages from other domains running in <code>iframe</code>s.
|
|
</dd>
|
|
|
|
<dt>Expiring stored data</dt>
|
|
<dd>
|
|
<p>User agents <em title="may" class="rfc2119">may</em> automatically delete stored data after a period
|
|
of time.</p>
|
|
|
|
<p>This can restrict the ability of a site to track a user, as the
|
|
site would then only be able to track the user across multiple
|
|
sessions when he authenticates with the site itself (e.g. by
|
|
making a purchase or logging in to a service).</p>
|
|
|
|
<p>However, this also puts the user's data at risk.</p>
|
|
</dd>
|
|
|
|
<dt>Treating persistent storage as cookies</dt>
|
|
<dd>
|
|
<p>User agents should present the database feature
|
|
to the user in a way that associates them strongly with HTTP
|
|
session cookies. [<cite><a href="#bib-COOKIES" rel="biblioentry" class="bibref">COOKIES</a></cite>]</p>
|
|
|
|
<p>This might encourage users to view such storage with healthy
|
|
suspicion.</p>
|
|
</dd>
|
|
|
|
<dt>Site-specific white-listing of access to databases</dt>
|
|
<dd>
|
|
<p>User agents <em title="may" class="rfc2119">may</em> require the user to authorize access to
|
|
databases before a site can use the feature.</p>
|
|
</dd>
|
|
|
|
<dt>Origin-tracking of stored data</dt>
|
|
<dd>
|
|
<p>User agents <em title="may" class="rfc2119">may</em> record the <span title="origin">origins</span>
|
|
of sites that contained content from third-party origins that
|
|
caused data to be stored.</p>
|
|
|
|
<p>If this information is then used to present the view of data
|
|
currently in persistent storage, it would allow the user to make
|
|
informed decisions about which parts of the persistent storage to
|
|
prune. Combined with a blacklist ("delete this data and prevent
|
|
this domain from ever storing data again"), the user can restrict
|
|
the use of persistent storage to sites that he trusts.</p>
|
|
</dd>
|
|
|
|
<dt>Shared blacklists</dt>
|
|
<dd>
|
|
<p>User agents <em title="may" class="rfc2119">may</em> allow users to share their persistent storage
|
|
domain blacklists.</p>
|
|
|
|
<p>This would allow communities to act together to protect their
|
|
privacy.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
While these suggestions prevent trivial use of this API for user
|
|
tracking, they do not block it altogether. Within a single domain, a
|
|
site can continue to track the user during a session, and can then
|
|
pass all this information to the third party along with any
|
|
identifying information (names, credit card numbers, addresses)
|
|
obtained by the site. If a third party cooperates with multiple
|
|
sites to obtain such information, a profile can still be
|
|
created.
|
|
</p>
|
|
|
|
<p>
|
|
However, user tracking is to some extent possible even with no
|
|
cooperation from the user agent whatsoever, for instance by using
|
|
session identifiers in URLs, a technique already commonly used for
|
|
innocuous purposes but easily repurposed for user tracking (even
|
|
retroactively). This information can then be shared with other
|
|
sites, using using visitors' IP addresses and other user-specific
|
|
data (e.g. user-agent headers and configuration settings) to combine
|
|
separate sessions into coherent user profiles.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="cookie-resurrection" class="section">
|
|
<h3><span class="secno">6.2 </span>Cookie resurrection</h3>
|
|
|
|
<p>
|
|
If the user interface for persistent storage presents data in the
|
|
persistent storage features described in this specification
|
|
separately from data in HTTP session cookies, then users are likely
|
|
to delete data in one and not the other. This would allow sites to
|
|
use the two features as redundant backup for each other, defeating a
|
|
user's attempts to protect his privacy.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="sensitivity-of-data" class="section">
|
|
<h3><span class="secno">6.3 </span>Sensitivity of data</h3>
|
|
|
|
<p>
|
|
User agents should treat persistently stored data as potentially
|
|
sensitive; it's quite possible for e-mails, calendar appointments,
|
|
health records, or other confidential documents to be stored in this
|
|
mechanism.
|
|
</p>
|
|
|
|
<p>To this end, user agents should ensure that when deleting data,
|
|
it is promptly deleted from the underlying storage.
|
|
</p>
|
|
</div>
|
|
</div> <!-- Privacy -->
|
|
|
|
<div id="authorization" class="section">
|
|
<!--OddPage--><h2><span class="secno">7. </span>Authorization</h2>
|
|
|
|
<div id="dns-spoofing-attacks" class="section">
|
|
<h3><span class="secno">7.1 </span>DNS spoofing attacks</h3>
|
|
|
|
<p>
|
|
Because of the potential for DNS spoofing attacks, one cannot
|
|
guarantee that a host claiming to be in a certain domain really is
|
|
from that domain. To mitigate this, pages can use SSL. Pages using
|
|
SSL can be sure that only pages using SSL that have certificates
|
|
identifying them as being from the same domain can access their
|
|
databases.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="cross-directory-attacks" class="section">
|
|
<h3><span class="secno">7.2 </span>Cross-directory attacks</h3>
|
|
|
|
<p>
|
|
Different authors sharing one host name, for example users
|
|
hosting content on <code>geocities.com</code>, all share one
|
|
set of databases.
|
|
</p>
|
|
|
|
<p>
|
|
There is no feature to restrict the access by pathname. Authors on
|
|
shared hosts are therefore recommended to avoid using these
|
|
features, as it would be trivial for other authors to read the data
|
|
and overwrite it.
|
|
</p>
|
|
|
|
<p class="note">Even if a path-restriction feature was made
|
|
available, the usual DOM scripting security model would make it
|
|
trivial to bypass this protection and access the data from any
|
|
path.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="implementation-risks" class="section">
|
|
<h3><span class="secno">7.3 </span>Implementation risks</h3>
|
|
|
|
<p>The two primary risks when implementing these persistent storage
|
|
features are letting hostile sites read information from other
|
|
domains, and letting hostile sites write information that is then
|
|
read from other domains.</p>
|
|
|
|
<p>Letting third-party sites read data that is not supposed to be
|
|
read from their domain causes <em>information leakage</em>, For
|
|
example, a user's shopping wish list on one domain could be used by
|
|
another domain for targeted advertising; or a user's
|
|
work-in-progress confidential documents stored by a word-processing
|
|
site could be examined by the site of a competing company.</p>
|
|
|
|
<p>Letting third-party sites write data to the persistent storage of
|
|
other domains can result in <em>information spoofing</em>, which is
|
|
equally dangerous. For example, a hostile site could add records to a
|
|
user's wish list; or a hostile site could set a user's session
|
|
identifier to a known ID that the hostile site can then use to track
|
|
the user's actions on the victim site.</p>
|
|
|
|
<p>Thus, strictly following the <span>origin</span> model described
|
|
in this specification is important for user security.</p>
|
|
</div>
|
|
</div> <!-- authorization -->
|
|
|
|
<div class="appendix section" id="requirements">
|
|
<!--OddPage--><h2><span class="secno">A. </span>Requirements</h2>
|
|
<div class="ednote">
|
|
Requirements will be written with an aim to verify that these were actually
|
|
met by the API specified in this document.
|
|
</div>
|
|
</div>
|
|
<div class="section appendix" id="acknowledgements">
|
|
<!--OddPage--><h2><span class="secno">B. </span>Acknowledgements</h2>
|
|
<div>
|
|
<p>
|
|
Special thanks and great appreciation to Nikunj Mehta, the original author of this specification,
|
|
who was employed by Oracle Corp when he wrote the early drafts.
|
|
</p>
|
|
</div>
|
|
<div>
|
|
<p>
|
|
Garret Swart was extremely influential in the design of this specification.
|
|
</p>
|
|
<p>
|
|
Special thanks to Chris Anderson, Pablo Castro, Dana Florescu, Israel Hilerio,
|
|
Arun Ranganathan, Margo Seltzer, Ben Turner, Shawn Wilsher, and Kris Zyp,
|
|
all of whose feedback and suggestions have led to improvements to this specification.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="appendix section" id="references">
|
|
<!--OddPage-->
|
|
<h2><span class="secno">C. </span>References</h2>
|
|
|
|
<div class="section" id="normative-references">
|
|
<h3><span class="secno">C.1 </span>Normative references</h3>
|
|
<dl class="bibliography">
|
|
<dt id="bib-COOKIES">[COOKIES]</dt>
|
|
<dd>
|
|
Adam Barth. <cite><a href="http://tools.ietf.org/html/draft-abarth-cookie">HTTP State Management Mechanism</a>.</cite>
|
|
IETF, November 2009
|
|
</dd>
|
|
<dt id="bib-DOM-LEVEL-3-EVENTS">[DOM-LEVEL-3-EVENTS]</dt>
|
|
<dd>
|
|
Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. <a href="http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/">
|
|
<cite>Document Object Model (DOM) Level 3 Events Specification.</cite></a> 31 May 2011. W3C Working Draft.
|
|
(Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/">http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/</a>
|
|
</dd>
|
|
<dt id="bib-DOM4">[DOM4]</dt>
|
|
<dd>
|
|
Anne van Kesteren; Ms2ger. <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html"><cite>DOM4.</cite></a> 7 September 2011.
|
|
W3C Editor's Draft. (Work in progress.) URL: <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html">http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html</a>
|
|
</dd>
|
|
<dt id="bib-ECMA-262">[ECMA-262]</dt>
|
|
<dd>
|
|
<a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm"><cite>ECMAScript Language Specification, Third Edition.</cite></a>
|
|
December 1999. URL: <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">http://www.ecma-international.org/publications/standards/Ecma-262.htm</a>
|
|
</dd>
|
|
<dt id="bib-HTML5">[HTML5]</dt>
|
|
<dd>
|
|
Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/html5"><cite>HTML5.</cite></a> 25 May 2011. W3C Working Draft.
|
|
(Work in progress.) URL: <a href="http://www.w3.org/TR/html5">http://www.w3.org/TR/html5</a>
|
|
</dd>
|
|
<dt id="bib-RFC2119">[RFC2119]</dt>
|
|
<dd>
|
|
S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997.
|
|
Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
|
|
</dd>
|
|
<dt id="bib-WEBIDL">[WEBIDL]</dt>
|
|
<dd>
|
|
Cameron McCormack. <a href="http://www.w3.org/TR/2008/WD-WebIDL-20081219"><cite>Web IDL.</cite></a> 19 December 2008.
|
|
W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2008/WD-WebIDL-20081219">http://www.w3.org/TR/2008/WD-WebIDL-20081219</a>
|
|
</dd>
|
|
<dt id="bib-WEBWORKERS">[WEBWORKERS]</dt>
|
|
<dd>
|
|
Ian Hickson. <a href="http://www.w3.org/TR/2011/WD-workers-20110310/"><cite>Web Workers.</cite></a> 10 March 2011.
|
|
W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-workers-20110310/">http://www.w3.org/TR/2011/WD-workers-20110310/</a>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
|
|
<div class="section" id="informative-references">
|
|
<h3><span class="secno">C.2 </span>Informative references</h3>
|
|
<dl class="bibliography">
|
|
<dt id="bib-WEBSTORAGE">[WEBSTORAGE]</dt>
|
|
<dd>
|
|
Ian Hickson. <a href="http://www.w3.org/TR/2009/WD-webstorage-20090910/"><cite>Web Storage.</cite></a> 10 September 2009.
|
|
W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-webstorage-20090910/">http://www.w3.org/TR/2009/WD-webstorage-20090910/</a>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|