← Back to branch summary

~lutostag/ubuntu/utopic/maas/1.5.2

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/cache/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-03-15 18:14:08 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20120315181408-zgl94hzo0x4n99an
Tags: 0.1+bzr295+dfsg-0ubuntu2
* debian/patches:
  - 01-fix-database-settings.patch: Update to set PSERV_URL.
  - 02-pserv-config.patch: Set port to 8001.
* debian/maas.postinst: Run maas-import-isos on install.
* debian/control: Depends on rabbitmq-server.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/cache/index.html
 
1
<!DOCTYPE html>
 
2
<html lang="en">
 
3
<head>
 
4
    <meta charset="utf-8">
 
5
    <title>Cache</title>
 
6
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
 
7
    <link rel="stylesheet" href="../assets/css/main.css">
 
8
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
 
9
    <script src="../../build/yui/yui-min.js"></script>
 
10
</head>
 
11
<body>
 
12
 
 
13
<div id="doc">
 
14
    <h1>Cache</h1>
 
15
 
 
16
    
 
17
        <a href="#toc" class="jump">Jump to Table of Contents</a>
 
18
    
 
19
 
 
20
    <div class="yui3-g">
 
21
        <div id="main" class="yui3-u">
 
22
            <div class="content"><div class="intro">
 
23
    <p>The Cache Utility provides a basic caching mechanism for storing key/value pairs in local JavaScript memory. As a subclass of Plugin, it is designed to seamlessly integrate with other components (such as <a href="../datasource/" title="YUI 3: DataSource">DataSource</a>).</p>
 
24
</div>
 
25
 
 
26
<h2 id="upgrade">Upgrade Notes</h2>
 
27
 
 
28
<dl>
 
29
    <dt>Cache as a plugin has changed</dt>
 
30
    <dd>Implementers upgrading from version 3.1.1 or earlier who are using Cache as a plugin now need to point to Y.Plugin.Cache instead of Y.Cache.</dd>
 
31
</dl>
 
32
 
 
33
<h2 id="getting-started">Getting Started</h2>
 
34
 
 
35
<p>
 
36
To include the source files for Cache and its dependencies, first load
 
37
the YUI seed file if you haven't already loaded it.
 
38
</p>
 
39
 
 
40
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
 
41
 
 
42
 
 
43
<p>
 
44
Next, create a new YUI instance for your application and populate it with the
 
45
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
 
46
YUI will automatically load any dependencies required by the modules you
 
47
specify.
 
48
</p>
 
49
 
 
50
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
 
51
YUI().use(&#x27;cache&#x27;, function (Y) {
 
52
    &#x2F;&#x2F; Cache is available and ready for use. Add implementation
 
53
    &#x2F;&#x2F; code here.
 
54
});</pre>
 
55
 
 
56
 
 
57
<p>
 
58
For more information on creating YUI instances and on the
 
59
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
 
60
documentation for the <a href="../yui/index.html">YUI Global object</a>.
 
61
</p>
 
62
 
 
63
 
 
64
<h2 id="using">Using the Cache</h2>
 
65
 
 
66
<p>This section describes how to use the Cache in further detail.</p>
 
67
 
 
68
<h3 id="base">Basic caching</h3>
 
69
 
 
70
<p>Basic caching allows you to store frequently used data in local JavaScript memory. In cases where data is retrieved over the wire from a server, you can store the response in a local cache and eliminate future trips to the server for better performance and reduced server load.</p>
 
71
 
 
72
<p>Use the following Attributes to configure your Cache instance:</p>
 
73
 
 
74
<table>
 
75
<thead>
 
76
    <tr>
 
77
        <th>Attribute</th>
 
78
        <th>Default</th>
 
79
        <th>Description</th>
 
80
    </tr>
 
81
</thead>
 
82
<tbody>
 
83
    <tr>
 
84
        <td><code>max</code></td>
 
85
        <td><code>0</code></td>
 
86
        <td>The maximum number of entries the cache can hold. <strong>The cache is disabled by default!</strong> Set this value to a number greater than zero to turn on caching.</td>
 
87
    </tr>
 
88
    <tr>
 
89
        <td><code>size</code></td>
 
90
        <td>n/a</td>
 
91
        <td>Read-only. Returns the number of entries currently stored in the cache.</td>
 
92
    </tr>
 
93
    <tr>
 
94
        <td><code>entries</code></td>
 
95
        <td>n/a</td>
 
96
        <td>Read-only. Returns an array of the entries currently stored in the cache.</td>
 
97
    </tr>
 
98
    <tr>
 
99
        <td><code>expires</code></td>
 
100
        <td><code>0</code></td>
 
101
        <td>By default, expiration is disabled. To enable expiration of data, set this value to the Date when the data should expire, or the relative number of milliseconds from collection that the data should expire.</td>
 
102
    </tr>
 
103
    <tr>
 
104
        <td><code>uniqueKeys</code></td>
 
105
        <td><code>false</code></td>
 
106
        <td>When calling add() with an entry, checks to see if the key is already stored in the cache. Enforcing unique keys requires iterating through all stored entries, so setting this attribute to <code>false</code> is more performant. Note: If expiration is enabled, you should probably set uniqueKeys to <code>false</code> to avoid problems if data is cached multiple times with conflicting expirations.</td>
 
107
    </tr>
 
108
</tbody>
 
109
</table>
 
110
 
 
111
<p>Here are the ways you can set the <code>max</code> value</strong> of a cache. <strong>You must set a <code>max</code> value to turn on caching.</strong></p>
 
112
        
 
113
<pre class="code prettyprint">&#x2F;&#x2F; Configure Cache maximum size in the constructor
 
114
var myCache = new Y.Cache({max:5});
 
115
 
 
116
&#x2F;&#x2F; Set the maximum size at runtime
 
117
myCache.set(&quot;max&quot;, 10);</pre>
 
118
 
 
119
 
 
120
<p><strong>Cache key/value pairs with the <code>add()</code> method.</strong></p>
 
121
 
 
122
<pre class="code prettyprint">&#x2F;&#x2F; Add entries to the Cache
 
123
myCache.add(&quot;key1&quot;, &quot;value1&quot;);</pre>
 
124
 
 
125
<p><strong>Retrieve cached entries with the <code>retrieve()</code> method.</strong> If there is no match for the given key, then <code>null</code> will be returned. Cached entries contain the properties <code>request</code>, <code>response</code>, <code>cached</code>, and <code>expires</code>.</p>
 
126
 
 
127
<pre class="code prettyprint">&#x2F;&#x2F; Retrieve a cached entry
 
128
var cachedEntry = cache.retrieve(&quot;key1&quot;);</pre>
 
129
 
 
130
 
 
131
<p>By default, cached entries may contain duplicate keys: if you add an entry for request "foo" with value "bar" and then add another entry for request "foo" with value "bat", the cache will contain both entries. Retrieving an entry for request "foo" will only retrieve the newest value. However, setting <code>uniqueKeys</code> to <code>true</code> will validate for the uniqueness of keys stored in the cache.</p>
 
132
 
 
133
<pre class="code prettyprint">&#x2F;&#x2F; Enforce unique keys in the constructor
 
134
var myCache = new Y.Cache({max:5, uniqueKeys:true});
 
135
 
 
136
&#x2F;&#x2F; Enforce unique keys at runtime
 
137
myCache.set(&quot;uniqueKeys&quot;, true);</pre>
 
138
 
 
139
 
 
140
<p>A cache may be flushed of all its entries with the <code>flush()</code> method.</p>
 
141
 
 
142
<pre class="code prettyprint">&#x2F;&#x2F; Flush the cache
 
143
myCache.flush();</pre>
 
144
 
 
145
<h3 id="offline">Offline caching</h3>
 
146
 
 
147
<p>The CacheOffline cache extends basic caching functionality by storing data in the <a href="http://stackoverflow.com/questions/2010892/storing-objects-in-html5-localstorage" title="Storing Objects in HTML5 localStorage - Stack Overflow">HTML5 localStorage object</a> on browsers where that is supported, so that data can be available when the browser is offline and can persist across browser sessions. In cases where HTML5 localStorage is not available (i.e., IE 6 and IE 7), the functionality falls back to basic caching in local JavaScript memory.</p>
 
148
 
 
149
<pre class="code prettyprint">var myCache = new Y.CacheOffline();</pre>
 
150
 
 
151
 
 
152
<p>Use the following Attributes to configure your CacheOffline instance:</p>
 
153
 
 
154
<table>
 
155
<thead>
 
156
    <tr>
 
157
        <th>Attribute</th>
 
158
        <th>Default</th>
 
159
        <th>Description</th>
 
160
    </tr>
 
161
</thead>
 
162
<tbody>
 
163
    <tr>
 
164
        <td><code>sandbox</code></td>
 
165
        <td><code>&quot;default&quot;</code></td>
 
166
        <td>A unique identifier used to sandbox each cache instance's entries from other entries. This string persists across browser sessions so take care that it is not dynamically generated.</td>
 
167
    </tr>
 
168
    <tr>
 
169
        <td><code>expires</code></td>
 
170
        <td><code>86400000</code></td>
 
171
        <td>By default, data will expire one day after it is cached. This Attribute accepts a Data value, or a number of milliseconds.</td>
 
172
    </tr>
 
173
    <tr>
 
174
        <td><code>max</code></td>
 
175
        <td><code>null</code></td>
 
176
        <td>Read-only. This Attribute is disabled for CacheOffline &#8212; there is no notion of capping the number of entries in a cache. Each browser implements a maximum localStorage byte size.</td>
 
177
    </tr>
 
178
    <tr>
 
179
        <td><code>uniqueKeys</code></td>
 
180
        <td><code>true</code></td>
 
181
        <td>Read-only. This Attribute is disabled for CacheOffline. All stored keys are unique.</td>
 
182
    </tr>
 
183
</tbody>
 
184
</table>
 
185
 
 
186
<h3 id="plugin">Cache as a plugin</h3>
 
187
 
 
188
<p>Use the <code>plug(Y.Plugin.Cache)</code> method on a host object to enable caching. The Y.Plugin.Cache class is available in the "cache-plugin" submodule.</p>
 
189
 
 
190
<pre class="code prettyprint">&#x2F;&#x2F; Define a max value to enable plugging.
 
191
myWidget.plug(Y.Plugin.Cache, {max:3});
 
192
myWidget.cache.add(&quot;key&quot;, &quot;value&quot;);</pre>
 
193
 
 
194
 
 
195
<p>The Cache plugin also accepts a <code>cache</code> value to enable you to point to any number of Cache implementations. Y.Cache and Y.CacheOffline are currently available.</p>
 
196
 
 
197
<pre class="code prettyprint">&#x2F;&#x2F; Define a max value to enable plugging.
 
198
myWidget.plug(Y.Plugin.Cache, {cache:Y.CacheOffline});</pre>
 
199
 
 
200
 
 
201
<p>The Y.Plugin.DataSourceCache plugin enables seamless caching of DataSource responses.</p>
 
202
 
 
203
<pre class="code prettyprint">&#x2F;&#x2F; Use a basic cache
 
204
myDataSource.plug(Y.Plugin.DataSourceCache, {
 
205
cache: Y.Cache, &#x2F;&#x2F; this is the default, this line is not needed
 
206
max: 100
 
207
});
 
208
 
 
209
&#x2F;&#x2F; Use the &quot;cache&quot; configuration property to enable offline caching
 
210
myDataSource.plug(Y.Plugin.DataSourceCache, {
 
211
cache: Y.CacheOffline,
 
212
sandbox: &quot;my3HrCache&quot;,
 
213
expires: 10800000 &#x2F;&#x2F; 3 hours
 
214
});</pre>
 
215
 
 
216
 
 
217
<p>Once the DataSourceCache plugin is enabled, it handles caching and retrieval of values without the need for extra code. Furthermore, all the methods and properties of the Cache instance is available on the host's <code>cache</code> namespace.</p>
 
218
 
 
219
<pre class="code prettyprint">&#x2F;&#x2F; Flush myDataSource&#x27;s cache.
 
220
myDataSource.cache.flush();</pre>
 
221
 
 
222
 
 
223
<h3 id="events">Events</h3>
 
224
 
 
225
<table>
 
226
<thead>
 
227
    <tr>
 
228
        <th>Event</th>
 
229
        <th>When</th>
 
230
        <th class="wrap">Properties available on the Event facade passed to handler</th>
 
231
    </tr>
 
232
</thead>
 
233
<tbody>
 
234
    <tr>
 
235
        <td><code>add</code></td>
 
236
        <td>Entry is added to the cache.</td>
 
237
        <td><dl>
 
238
            <dt><code>entry</code></dt>
 
239
            <dd>The cached entry.</dd>
 
240
        </dl></td>
 
241
    </tr>
 
242
    <tr>
 
243
        <td><code>request</code></td>
 
244
        <td>Entry is requested from the cache.</td>
 
245
        <td><dl>
 
246
            <dt><code>request</code></dt>
 
247
            <dd>The request value.</dd>
 
248
        </dl></td>
 
249
    </tr>
 
250
    <tr>
 
251
        <td><code>retrieve</code></td>
 
252
        <td>Entry is retrieved from the cache.</td>
 
253
        <td><dl>
 
254
            <dt><code>entry</code></dt>
 
255
            <dd>The retrieved entry.</dd>
 
256
        </dl></td>
 
257
    </tr>
 
258
    <tr>
 
259
        <td><code>flush</code></td>
 
260
        <td>Cache is flushed.</td>
 
261
        <td>none</td>
 
262
    </tr>
 
263
    <tr>
 
264
        <td><code>error</code></td>
 
265
        <td>CacheOffline only. Fired when an entry could not be added, most likely due to exceeding the browser quota for the localStorage object.</td>
 
266
        <td><dl>
 
267
            <dt><code>error</code></dt>
 
268
            <dd>The error object.</dd>
 
269
        </dl></td>
 
270
    </tr>
 
271
</tbody>
 
272
</table>
 
273
</div>
 
274
        </div>
 
275
 
 
276
        <div id="sidebar" class="yui3-u">
 
277
            
 
278
                <div id="toc" class="sidebox">
 
279
                    <div class="hd">
 
280
                        <h2 class="no-toc">Table of Contents</h2>
 
281
                    </div>
 
282
 
 
283
                    <div class="bd">
 
284
                        <ul class="toc">
 
285
<li>
 
286
<a href="#upgrade">Upgrade Notes</a>
 
287
</li>
 
288
<li>
 
289
<a href="#getting-started">Getting Started</a>
 
290
</li>
 
291
<li>
 
292
<a href="#using">Using the Cache</a>
 
293
<ul class="toc">
 
294
<li>
 
295
<a href="#base">Basic caching</a>
 
296
</li>
 
297
<li>
 
298
<a href="#offline">Offline caching</a>
 
299
</li>
 
300
<li>
 
301
<a href="#plugin">Cache as a plugin</a>
 
302
</li>
 
303
<li>
 
304
<a href="#events">Events</a>
 
305
</li>
 
306
</ul>
 
307
</li>
 
308
</ul>
 
309
                    </div>
 
310
                </div>
 
311
            
 
312
 
 
313
            
 
314
                <div class="sidebox">
 
315
                    <div class="hd">
 
316
                        <h2 class="no-toc">Examples</h2>
 
317
                    </div>
 
318
 
 
319
                    <div class="bd">
 
320
                        <ul class="examples">
 
321
                            
 
322
                                
 
323
                                    <li data-description="Basic caching functionality with the Cache Utility.">
 
324
                                        <a href="cache-basic.html">Basic Caching</a>
 
325
                                    </li>
 
326
                                
 
327
                            
 
328
                                
 
329
                                    <li data-description="Offline caching implements HTML 5 localStorage when available, to allow data to persist across browser sessions.">
 
330
                                        <a href="cache-offline.html">Offline Caching</a>
 
331
                                    </li>
 
332
                                
 
333
                            
 
334
                                
 
335
                            
 
336
                                
 
337
                            
 
338
                        </ul>
 
339
                    </div>
 
340
                </div>
 
341
            
 
342
 
 
343
            
 
344
                <div class="sidebox">
 
345
                    <div class="hd">
 
346
                        <h2 class="no-toc">Examples That Use This Component</h2>
 
347
                    </div>
 
348
 
 
349
                    <div class="bd">
 
350
                        <ul class="examples">
 
351
                            
 
352
                                
 
353
                            
 
354
                                
 
355
                            
 
356
                                
 
357
                                    <li data-description="Use the DataSourceCache plugin to enable caching and reduce server calls to remote sources.">
 
358
                                        <a href="../datasource/datasource-caching.html">DataSource with Caching</a>
 
359
                                    </li>
 
360
                                
 
361
                            
 
362
                                
 
363
                                    <li data-description="The DataSourceCache plugin supports offline caching so that cached data persists across browser sessions.">
 
364
                                        <a href="../datasource/datasource-offlinecache.html">DataSource with Offline Cache</a>
 
365
                                    </li>
 
366
                                
 
367
                            
 
368
                        </ul>
 
369
                    </div>
 
370
                </div>
 
371
            
 
372
        </div>
 
373
    </div>
 
374
</div>
 
375
 
 
376
<script src="../assets/vendor/prettify/prettify-min.js"></script>
 
377
<script>prettyPrint();</script>
 
378
 
 
379
</body>
 
380
</html>