The LocalServer module is a specialized URL cache that the web application controls. Requests for URLs in the LocalServer's cache are intercepted and served locally from the user's disk.

Applications manage the cache using two classes:

ResourceStore - for capturing ad-hoc URLs using JavaScript. The ResourceStore allows an application to capture user data files that need to be addressed with a URL, such as a PDF file or an image. ManagedResourceStore - for capturing a related set of URLs that are declared in a manifest file, and are updated automatically. The ManagedResourceStore allows the set of resources needed to run a web application to be captured.

For both types of stores, the set of URLs captured is explicitly controlled by the web application.

Serving and updating cached resources

The LocalServer intercepts HTTP/HTTPS requests and serves them from the cache when all of these conditions are met:

The URL is cached in a ResourceStore or ManagedResourceStore, The store's enabled attribute is set to true, and If the store has a requiredCookie attribute, the request must have a cookie that matches. For further details read Cookies and the LocalServer.

The LocalServer always serves a cached resource when the conditions are met, regardless of the network connection. The URLs contained in a store are eligible for local serving without requiring the application to open the store.

To disable local serving of stored resources and force URLs to be served using the regular network connection, the application can set the store's enabled attribute to false.

A key difference between the two types of stores is how resources are updated. The contents of a ManagedResourceStore are automatically updated periodically by Gears, even if the web developer never calls checkForUpdate(). For more information, see ManagedResourceStore Updates. The ResourceStore's contents are never automatically updated, and are only updated when the developer explicitly calls capture().

Permission

This API requires user permission. If you would like to customize the default dialog, you can explicitly call google.gears.factory.getPermission() - see how.

Example

<script type="text/javascript" src="gears_init.js"></script>
<script type="text/javascript">
var localServer = google.gears.factory.create('beta.localserver');
var store = localServer.createManagedStore('test-store');
store.manifestUrl = 'site-manifest.txt';
store.checkForUpdate();
</script>

// site-manifest.txt
{
  "betaManifestVersion": 1,
  "version": "site_version_string",
  "entries": [
    { "url": "site.html" },
    { "url": "gears_init.js" }
  ]
}

Classes

LocalServer class
   boolean              canServeLocally(string url)
   ResourceStore        createStore(string name, [string requiredCookie])
   ResourceStore        openStore(string name, [string requiredCookie])
   void                 removeStore(string name, [string requiredCookie])
   ManagedResourceStore createManagedStore(string name, [string requiredCookie])
   ManagedResourceStore openManagedStore(string name, [string requiredCookie])
   void                 removeManagedStore(string name, [string requiredCookie])

ManagedResourceStore class
   readonly  attribute string  name
   readonly  attribute string  requiredCookie
   readwrite attribute boolean enabled
   readwrite attribute string  manifestUrl
   readonly  attribute int     lastUpdateCheckTime
   readonly  attribute int     updateStatus
   readonly  attribute string  lastErrorMessage
   readonly  attribute string  currentVersion
   event void oncomplete(Object details)
   event void onerror(Error error)
   event void onprogress(Object details)
   void checkForUpdate()

ResourceStore class
   readonly  attribute string  name
   readonly  attribute string  requiredCookie
   readwrite attribute boolean enabled
   int           capture(string urlOrUrlArray, completionCallback)
   void          abortCapture(int captureId)
   void          remove(string url)
   void          rename(string srcUrl, string destUrl)
   void          copy(string srcUrl, string destUrl)
   boolean       isCaptured(string url)
   void          captureFile(fileInputElement, url)
   string        getCapturedFileName(url)
   string        getHeader(string url, string name)
   string        getAllHeaders(string url)
   FileSubmitter createFileSubmitter()

FileSubmitter class
   void      setFileInputElement(htmlElement el, string url)

LocalServer class

The LocalServer is a factory and container for the set of ResourceStores and ManagedResourceStores your application creates and uses. Use resource stores to enable your JavaScript application to execute without a network connection.

To create a LocalServer object, use the Gears Factory as follows:

<script type="text/javascript" src="gears_init.js"></script>
<script type="text/javascript">
var localServer = google.gears.factory.create('beta.localserver');
</script>

Methods

canServeLocally(string url)

Return Value boolean

Parameters url - relative or absolute URL that is from the same origin as the current page

Exceptions Throws an exception if the URL is not from the same origin as the current page.

Description Returns true if a request for the URL can be satisfied from any of the resource stores available, taking into account whether the containing store is enabled and if its requiredCookie matches. Relative URLs are interpreted according to the current page location.

createStore(string name, [string requiredCookie])

Return Value ResourceStore

Parameters name - string identifying the store.
requiredCookie - optional.
The combination of name and requiredCookie (along with the domain) identify a unique store.
Expected cookie format is "name=value".