Local Server

read me file for local server application

Title read me file for local server application
Author(s) LiXizhi
Date 2008/2/25
File script/kids/3DMapSystemApp/localserver/readme.lua

Description

developer guide and samples for local server app

TIP Sample Code

NPL.load("(gl)script/kids/3DMapSystemApp/localserver/readme.lua");

what is a local server?

The LocalServer module allows a web application to cache and serve its HTTP resources locally, without a network connection.

Overview

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.

Resource stores

A resource store is a container of URLs. Using the LocalServer module, applications can create any number of resource stores, and a resource store can contain any number of URLs.

There are two types of resource stores: - 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.

Architecture & Implementation Notes

all sql database manipulation functions are exposed via WebCacheDB, whose implementation is split in WebCacheDB* files. localserver is the based class for two servers: ResourceStore and ManagedResourceStore.

Using Local server as a local database

One can use local server as a simple (name, value) pair database with cache_policy functions.

To query a database entry call below, here we will use web service store

   local ls = Map3DSystem.localserver.CreateStore(nil, 2);
   if(not ls) then
      return 
   end
   cache_policy = cache_policy or Map3DSystem.localserver.CachePolicy:new("access plus 1 week");
   
   local url = Map3DSystem.localserver.UrlHelper.WS_to_REST(fakeurl_query_miniprofile, {JID=JID}, {"JID"});
   local item = ls:GetItem(url)
   if(item and item.entry and item.payload and not cache_policy:IsExpired(item.payload.creation_date)) then
      -- NOTE:item.payload.data is always a string, one may deserialize from it to obtain table object.
      local profile = item.payload.data;
      if(type(callbackFunc) == "function") then
         callbackFunc(JID, profile);
      end
   else
      
   end

To add(update) a database entry call below

   local ls = Map3DSystem.localserver.CreateStore(nil, 2);
   if(not ls) then
      return 
   end
   -- make url
   local url = Map3DSystem.localserver.UrlHelper.WS_to_REST(fakeurl_query_miniprofile, {JID=JID}, {"JID"});

   -- make entry
   local item = {
      entry = Map3DSystem.localserver.WebCacheDB.EntryInfo:new({
         url = url,
      }),
      payload = Map3DSystem.localserver.WebCacheDB.PayloadInfo:new({
         status_code = Map3DSystem.localserver.HttpConstants.HTTP_OK,
         data = msg.profile,
      }),
   }
   -- save to database entry
   local res = ls:PutItem(item) 
   if(res) then 
      log("ls put JID mini profile for "..url.."\n")
   else
      log("warning: failed saving JID profile item to local server.\n")
   end
<verbatim>


---++ Lazy writing 

For the URL history, this transaction commit overhead is unacceptably high(0.05s for the most simple write commit). 
On some systems, the cost of committing a new page to the history database was as high as downloading the entire page 
and rendering the page to the screen. As a result, ParaEngine's localserver has implemented a lazy sync system. 

Please see  https://developer.mozilla.org/en/Storage/Performance, for a reference

Localserver has relaxed the ACID requirements in order to speed up commits. In particular, we have dropped durability. 
This means that when a commit returns, you are not guaranteed that the commit has gone through. If the power goes out 
right away, that commit may (or may not) be lost. However, we still support the other (ACI) requirements. 
This means that the database will not get corrupted. If the power goes out immediately after a commit, the transaction 
will be like it was rolled back: the database will still be in a consistent state. 

]]
---++ creating instances of local servers
| *Title* | creating instances of local servers |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/27 |
| *File* | script/kids/3DMapSystemApp/localserver/factory.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/factory.lua");
local store = Map3DSystem.localserver.CreateStore("WebserviceStore_sample", 2)
local store = Map3DSystem.localserver.CreateStore("ResourceStore_sample", 1)
local store = Map3DSystem.localserver.CreateStore("ManagedResourceStore_sample", 0)
</verbatim>

---+++ Member Functions

---++++ !Map3DSystem.localserver.GetStore

 get the loaded store. if the store is not loaded,it will return nil. To CreateGet a store, use CreateStore() instead. 


__syntax__
<verbatim>function Map3DSystem.localserver.GetStore(name)</verbatim>


__parameters__

| *name* |  |

---++ cache policy
| *Title* | cache policy |
| *Author(s)* | LiXizhi |
| *Date* | 2008/3/2 |
| *File* | script/kids/3DMapSystemApp/localserver/cache_policy.lua |
---+++ Description
In NPL local server, there is a single cache policy which is slight different from standard HTTP cache 
(The official version is here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9)

---++ NPL local server caching policy
 The cache policy by NPL local server (and represented by this CachePolicy class) is stated below:
   * find the entry in the local server. If a completed entry is found, it is always returned immediately, regardless of whether it has expired or not. 
   * if no entry is found or the entry expired, a new entry will be fetched via remote server and updated in the local server. 
   * When a entry is updated in the store, it will be returned to all callback functions registered to it. 
__Note1__: It means that the same request might be returned twice. The first time is the local version at the time of call; and the second time is when the entry is just updated via the server. 
The second call is skipped if the server can verify that the content has not changed and only update the last access time in the local store. 
__Note2__: If the relative expire time is 0, the first call is ignored. 
__Note3__: If the relative expire time is larger than a year, the second call is always ignored. 
__Note4__: This same policy applies to ResourceStore, ManagedResourceStore, and WebserviceStore.For WebserviceStore, only access base time type is permitted. The server policy can be overwritten by local server policy, local server policy can be overwritten by per function policy

To increase efficiency, one can create several different cache policy objects and share them for all local stores and related function calls. 

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/cache_policy.lua");
local cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 month");
cache_policy:IsExpired(ParaGlobal.GetSysDateTime()-80000);

-- there are some premade policies, which can be retrieve from Map3DSystem.localserver.CachePolicies, see below
local cp = Map3DSystem.localserver.CachePolicies["never"];
local cp = Map3DSystem.localserver.CachePolicies["always"];
local cp = Map3DSystem.localserver.CachePolicies["1 hour"];
local cp = Map3DSystem.localserver.CachePolicies["1 day"];
</verbatim>

---+++ Member Functions

---++++ !CachePolicy:new

<verbatim>--------------------------
 CachePolicy class
--------------------------

local CachePolicy = {
   -- The base time is either the last modification time of the file, or the time of the client's access to the document.
   -- 0 means that the file's last modification time should be used as the base time, 
   -- 1 means the client's access time should be used.
   -- nil Expiration is not enabled. 
   BaseTime = 1,
   -- Time in seconds to expire relative to BaseTime. e.g. 2592000 is a month, which is good for asset and images.  604800 is a week which is good for profile and content pages. 
   ExpireTime = 604800,
}</verbatim>;

commonlib.setfield("Map3DSystem.localserver.CachePolicy", CachePolicy);

 create the object and init from initCode. 
 format of initCode, please see Init() function. 


__syntax__
<verbatim>function CachePolicy:new(initCode)</verbatim>


__parameters__

| *initCode* |  |

---++++ !CachePolicy:Init

[[ Extacts the policy base time type expire time from an input string. 
   * _param_ __initCode__ : string: it has the following syntax
"<base> [plus] {<num> <type>}*"
where <base> is one of: access, now (equivalent to 'access'), modification 
The plus keyword is optional <num> should be an integer value, and <type> is one of: years months weeks days hours minutes seconds 
For example, any of the following can be used to make entries expire 1 month after being accessed:
   - "access plus 1 month"
   - "access plus 4 weeks"
   - "access plus 30 days" 
The expiry time can be fine-tuned by adding several '<num> <type>' clauses:
   - "access plus 1 month 15 days 2 hours"
   - "modification plus 5 hours 3 minutes" 
   * _return_ ____ : Returns true if successful. 
]]


__syntax__
<verbatim>function CachePolicy:Init(initCode)</verbatim>


__parameters__

| *initCode* | string: it has the following syntax
"<base> [plus] {<num> <type>}*"
where <base> is one of: access, now (equivalent to 'access'), modification 
The plus keyword is optional <num> should be an integer value, and <type> is one of: years months weeks days hours minutes seconds 
For example, any of the following can be used to make entries expire 1 month after being accessed:
   - "access plus 1 month"
   - "access plus 4 weeks"
   - "access plus 30 days" 
The expiry time can be fine-tuned by adding several '<num> <type>' clauses:
   - "access plus 1 month 15 days 2 hours"
   - "modification plus 5 hours 3 minutes" |

---++++ !CachePolicy:IsExpired

 whether time is expired.
   * _param_ __Basetime__ : the base time in second
   * _return_ ____ : true if input time is expired


__syntax__
<verbatim>function CachePolicy:IsExpired(Basetime)</verbatim>


__parameters__

| *Basetime* | the base time in second |

---++++ !CachePolicy:IsCacheEnabled

   * _return_ __whether__ : cache is enabled. i.e. self.ExpireTime is not 0. 


__syntax__
<verbatim>function CachePolicy:IsCacheEnabled()</verbatim>


__parameters__

| *return* | cache is enabled. i.e. self.ExpireTime is not 0. |

---++++ !CachePolicy:IsCacheAlwaysUsed

   * _return_ __whether__ : cache is always used. i.e. self.ExpireTime over 1 year. 


__syntax__
<verbatim>function CachePolicy:IsCacheAlwaysUsed()</verbatim>


__parameters__

| *return* | cache is always used. i.e. self.ExpireTime over 1 year. |

---++ A CaptureTask processes a CaptureRequest asynchronously in the background
| *Title* | A CaptureTask processes a CaptureRequest asynchronously in the background |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/27 |
| *File* | script/kids/3DMapSystemApp/localserver/capture_task.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/capture_task.lua");
</verbatim>

---+++ Member Functions

---++++ !TaskManager:new_request

<verbatim>------------------------------------------------------------------------------
 A CaptureRequest encapslates the parameters to a ResourceStore.capture() API call. Multiple urls can be specified in a single API call.
 Note: Use TaskManager:new_request() to create an instance of this class
------------------------------------------------------------------------------
local CaptureRequest  = {
   -- int: captureId assigned by ResourceStore for this request
   id,
   -- request type, if nil, it is auto determined. this is 1 for URL request; and 2 for file request. 
   type = nil,
   -- url string or array of un-resolved urls provided by the caller
   urls = nil,
   -- url string or array of resolved urls in the same order as urls
   full_urls = nil,
   -- [optional] request msg of web service. only used when the request urls are for npl web services. 
   msg = nil,
   -- function to call when the a url request is complete. function(msg, callbackContext or url) end, where msg is the returned msg if any, url if the url that has responded. 
   callbackFunc = nil,
   -- this is an optional parameter that is passed to callbackFunc and OnTaskComplete
   callbackContext = nil,
   -- nil or function to call when the all urls in the request are completed. function(succeed, callbackContext) end
   OnTaskComplete = nil,
   
};
Map3DSystem.localserver.CaptureRequest = CaptureRequest;

------------------------------------------------------------------------------
 TaskManager keeps a list of active task, one should use the task manager to add new request/task. 
 the task manager will only start a new task if there is no previous same task or the previous one times out. 
 this is a singleton class. 
------------------------------------------------------------------------------
local TaskManager = {
   -- mapping from request id to their associated CaptureTask. 
   tasks = {},
   -- urls that is currently being processed. mapping from url to true. 
   urls={},
   -- next request id, increased by one when each new request is created. 
   next_request_id = 0,
}</verbatim>;
Map3DSystem.localserver.TaskManager = TaskManager;

 create a new request for urls. it will return nil if there is already a same request being processed.
 Note: this function will add urls to self.urls
   * _param_ __urls__ : [in|out] url string or an array of un-resolved urls provided by the caller
   * _param_ __requestType__ : nil if undetermined. 1 for url request, and 2 for file download request. 
 if it is an array, when the function returns, urls that are being processed will be removed. 


__syntax__
<verbatim>function TaskManager:new_request(urls, requestType)</verbatim>


__parameters__

| *urls* | [in|out] url string or an array of un-resolved urls provided by the caller |
| *requestType* |  |

---++++ !TaskManager:HasUrl

 return true if there is already a url being processed. 
   * _param_ __url__ : url string. 


__syntax__
<verbatim>function TaskManager:HasUrl(url)</verbatim>


__parameters__

| *url* | url string. |

---++++ !TaskManager:GetTask

 return the task object by it request id.  


__syntax__
<verbatim>function TaskManager:GetTask(request_id)</verbatim>


__parameters__

| *request* |  |
| *id* |  |

---++++ !Map3DSystem.localserver.ProcessURLRequest_result

 process a finished url request 
   * _param_ __request__ :_id: request id 
   * _param_ __index__ : url index in the request


__syntax__
<verbatim>function Map3DSystem.localserver.ProcessURLRequest_result(request_id, index)</verbatim>


__parameters__

| *request* | _id: request id |
| *id* |  |
| *index* |  |

---++++ !Map3DSystem.localserver.ProcessWS_result

 process a finished web service
   * _param_ __request__ :_id: request id 
   * _param_ __index__ : url index in the request


__syntax__
<verbatim>function Map3DSystem.localserver.ProcessWS_result(request_id, index)</verbatim>


__parameters__

| *request* | _id: request id |
| *id* |  |
| *index* |  |

---++++ !Map3DSystem.localserver.ProcessFile_result

 process a NPL.AsyncDownload result
   * _param_ __request__ :_id: request id 
   * _param_ __index__ : url index in the request


__syntax__
<verbatim>function Map3DSystem.localserver.ProcessFile_result(request_id, index)</verbatim>


__parameters__

| *request* | _id: request id |
| *id* |  |
| *index* |  |

---++++ !CaptureTask:new

<verbatim>------------------------------------------------------------------------------
 A CaptureTask processes a CaptureRequest asynchronously in the background. 
 Notification messages are sent to the listener as each url in the request is completed.
------------------------------------------------------------------------------
local CaptureTask = {
   -- Notification message codes sent to listeners
   CAPTURE_TASK_COMPLETE = 0,
   CAPTURE_URL_SUCCEEDED = 1,
   CAPTURE_URL_FAILED = 2,
   
   -- a reference to the ResourceStore making this capture
   store_ = nil,
   -- type of CaptureRequest
   capture_request_ = nil,
   -- mapping from finished url to true. 
   processed_urls_ = nil,
   
   --
   -- For async task
   --
   -- whether initialized
   is_initialized_ = nil,
   is_aborted_ = nil,
}</verbatim>;
Map3DSystem.localserver.CaptureTask = CaptureTask;

 return the task object if succeed. otherwise nil.
 upon created it will be automatically added to the TaskManager. The capture task can be accessed via its request id, 
 and will be automatically removed when the task is completed. 
   * _param_ __store__ : the ResourceStore object
   * _param_ __request__ : type of CaptureRequest, usually from TaskManager:new_request(urls);


__syntax__
<verbatim>function CaptureTask:new(store, request)</verbatim>


__parameters__

| *store* | the ResourceStore object |
| *request* |  |

---++++ !CaptureTask:Init

 return true if succeed. otherwise nil. 
 upon return it will be automatically added to the TaskManager. The capture task can be accessed via its request id, 
   * _param_ __store__ : the ResourceStore object
   * _param_ __request__ : type of CaptureRequest


__syntax__
<verbatim>function CaptureTask:Init(store, request)</verbatim>


__parameters__

| *store* | the ResourceStore object |
| *request* |  |

---++++ !CaptureTask:Abort

 Gracefully aborts the task that was previously started


__syntax__
<verbatim>function CaptureTask:Abort()</verbatim>

---++++ !CaptureTask:Run

 run and process all requests one by one.
   * _param_ __index__ : from which index to process. if nil, it will be 1. 


__syntax__
<verbatim>function CaptureTask:Run(index)</verbatim>


__parameters__

| *index* | from which index to process. if nil, it will be 1. |

---++++ !CaptureTask:Release

 close and remove from task pool


__syntax__
<verbatim>function CaptureTask:Release()</verbatim>

---++++ !CaptureTask:AddProcessedUrl

 add a processed url. 


__syntax__
<verbatim>function CaptureTask:AddProcessedUrl(url)</verbatim>


__parameters__

| *url* |  |

---++++ !CaptureTask:ProcessUrl

 NOT USED: return true if processed. 


__syntax__
<verbatim>function CaptureTask:ProcessUrl(url)</verbatim>


__parameters__

| *url* |  |

---++++ !CaptureTask:NotifyUrlProgress

   * _param_ __msg__ : data to be passed to the user specified callback. It usually contains the progress of the given url
 format is msg = {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number} is the input


__syntax__
<verbatim>function CaptureTask:NotifyUrlProgress(index, msg)</verbatim>


__parameters__

| *index* |  |
| *msg* | data to be passed to the user specified callback. It usually contains the progress of the given url
 format is msg = {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number} is the input |

---++++ !CaptureTask:NotifyUrlComplete

   * _param_ __msg__ : data to be passed to the user specified callback. could be web service msg or entry object for files. 
   * _return_ ____ : true is returned if msg is not nil after msg translation. 


__syntax__
<verbatim>function CaptureTask:NotifyUrlComplete(index, msg)</verbatim>


__parameters__

| *index* |  |
| *msg* | data to be passed to the user specified callback. could be web service msg or entry object for files. |

---++ WebserviceStore : public <ResourceStore>: public <localserver>
| *Title* | WebserviceStore : public <ResourceStore>: public <localserver> |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/28 |
| *File* | script/kids/3DMapSystemApp/localserver/WebserviceStore.lua |
---+++ Description
A WebserviceStore represents a set of web service response entries in the WebCacheDB and allows the set to be managed as a group. 
The identifying properties of a LocalServer are its domain, name, required_cookie, and server_type.

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/WebserviceStore.lua");
</verbatim>

---+++ Member Functions

---++++ !WebserviceStore:CallRestEx

<verbatim>------------------------------------------
 WebserviceStore : public <localserver>
------------------------------------------
local WebserviceStore = commonlib.inherit(Map3DSystem.localserver.ResourceStore, {
   -- type of WebCacheDB.ServerType
   server_type_ = WebCacheDB.ServerType.WEBSERVICE_STORE,
   -- default policy
   Cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 hour"),
   Cache_policy_REST = Map3DSystem.localserver.CachePolicy:new("access plus 1 week"),
}</verbatim>);

commonlib.setfield("Map3DSystem.localserver.WebserviceStore", WebserviceStore);

----------------------------------
 functions: 
----------------------------------
 call a HTML or other text page from the local server, using a local_cache_policy
 If there is already a completed HTML pagebefore, we will return the response immediately. And then still proceed to do the update check if expired. 
   * _param_ __Cache__ :_policy: nil or default Cache_policy_REST. (one week time)
   * _param_ __url__ : url of the HTML page
   * _param_ __callbackFunc__ : the call back function(entry, callbackContext or url) end, 
  entry.payload.cached_filepath is name of the file that contains the text returned via HTTP, usually it is xml, html, mcml, etc. so caller can construct an xml tree from it. 
  Note that the callbackFunc may be called before this function returns since the request may be served locally. 
   * _param_ __callbackContext__ : this is an optional parameter that is passed to callbackFunc
   * _return_ __return__ : true if it is fetching data or data is already available. it return nil or paraworld.errorcode, if web service can not be called at this time, due to error or too many concurrent calls.


__syntax__
<verbatim>function WebserviceStore:CallRestEx(Cache_policy, url, callbackFunc, callbackContext)</verbatim>


__parameters__

| *Cache* | _policy: nil or default Cache_policy_REST. (one week time) |
| *policy* |  |
| *url* |  |
| *callbackFunc* | the call back function(entry, callbackContext or url) end, 
  entry.payload.cached_filepath is name of the file that contains the text returned via HTTP, usually it is xml, html, mcml, etc. so caller can construct an xml tree from it. 
  Note that the callbackFunc may be called before this function returns since the request may be served locally. |
| *callbackContext* |  |
| *return* | true if it is fetching data or data is already available. it return nil or paraworld.errorcode, if web service can not be called at this time, due to error or too many concurrent calls. |

---++++ !WebserviceStore:CallXML

 Same as CallRestEx. the only difference is that callbackFunc(xmlRootNode, entry, callbackContext) contains the xml table, instead of entry object. 


__syntax__
<verbatim>function WebserviceStore:CallXML(Cache_policy, url, callbackFunc, callbackContext)</verbatim>


__parameters__

| *Cache* |  |
| *policy* |  |
| *url* |  |
| *callbackFunc* |  |
| *callbackContext* |  |

---++++ !WebserviceStore:CallWebserviceEx

 call a web service from the local server, using a local_cache_policy
 If there is already a completed response before, we will return the response immediately. And then still proceed to do the update check  if expired.  
   * _param_ __Cache__ :_policy: nil or Map3DSystem.localserver.CachePolicy
   * _param_ __url__ : url of the web service
   * _param_ __msg__ : an NPL table to be sent. 
   * _param_ __REST__ :_policy: an array of variable names in the msg from which the web service request is converted to a REST style url.
 a REST style url encodes both the web services url and msg data. see UrlHelper for details. 
   * _param_ __callbackFunc__ : the call back function(msg, callbackContext or url) end, 
  Note that the callbackFunc may be called before this function returns since the request may be served locally. 
   * _param_ __callbackContext__ : this is an optional parameter that is passed to callbackFunc
   * _return_ __return__ : true if it is fetching data or data is already available. 


__syntax__
<verbatim>function WebserviceStore:CallWebserviceEx(Cache_policy, url, msg, REST_policy, callbackFunc, callbackContext) </verbatim>


__parameters__

| *Cache* | _policy: nil or Map3DSystem.localserver.CachePolicy |
| *policy* |  |
| *url* |  |
| *msg* | an NPL table to be sent. |
| *REST* |  |
| *policy* |  |
| *callbackFunc* | the call back function(msg, callbackContext or url) end, 
  Note that the callbackFunc may be called before this function returns since the request may be served locally. |
| *callbackContext* |  |
| *return* | true if it is fetching data or data is already available. |

---++ ResourceStore : public <localserver>
| *Title* | ResourceStore : public <localserver> |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/25 |
| *File* | script/kids/3DMapSystemApp/localserver/ResourceStore.lua |
---+++ Description
A ResourceStore represents a set of entries in the WebCacheDB and allows the set to be managed as a group. 
The identifying properties of a LocalServer are its domain, name, required_cookie, and server_type.

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/ResourceStore.lua");
</verbatim>

---+++ Member Functions

---++++ !ResourceStore.AppendHeader

<verbatim>------------------------------------------
 ResourceStore : public <localserver>
------------------------------------------
local ResourceStore = commonlib.inherit(Map3DSystem.localserver.localserver, {
   -- type of WebCacheDB.ServerType
   server_type_ = WebCacheDB.ServerType.RESOURCE_STORE,
   
   -- int64: The rowid of the version record in the DB associated with this
   -- ResourceStore. Each ResourceStore has exactly one related
   -- version record. The schema requires that Servers contain Versions
   -- contain Entries in order to support the other class of Server, the
   -- ManagedResourceStore. To satisfy the schema, this class manages
   -- the lifecyle of this record in the version table. When the Server
   -- record is inserted and delete, the Version record goes in lock step.
   version_id_;
   -- default policy
   Cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 day"),
}</verbatim>);

commonlib.setfield("Map3DSystem.localserver.ResourceStore", ResourceStore);

 private helper function


__syntax__
<verbatim>function ResourceStore.AppendHeader(headers, name, value) </verbatim>


__parameters__

| *headers* |  |
| *name* |  |
| *value* |  |

---++++ !ResourceStore:GetFile

----------------------------------
 major API functions: 
----------------------------------

 retrieve all url files using the local server. 
   * _param_ __Cache__ :_policy: nil or Map3DSystem.localserver.CachePolicy
   * _param_ __urls__ : url string or an array of urls. It will be retrieved one after another.
   * _param_ __callbackFunc__ : the call back function(entry, callbackContext or url) end will be called for each url in input urls.
   * _param_ __callbackContext__ : this is an optional parameter that is passed to callbackFunc
  where the entry is a table of {entry, payload, IsFromCache}. Normally, one can access the disk file 
  containing the reponse data by entry.payload.cached_filepath
  and other info by entry.payload:GetHeader(Map3DSystem.localserver.HttpConstants.kXXX);
   * _param_ __callbackProgressFunc__ : this is an optional function that is called whenever a fraction of a url is downloaded
 the format is function(msg, callbackContext or url), where msg is {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number}
   * _return_ __return__ : true if it is fetching data or data is already available. 


__syntax__
<verbatim>function ResourceStore:GetFile(Cache_policy, urls, callbackFunc, callbackContext, callbackProgressFunc) </verbatim>


__parameters__

| *Cache* | _policy: nil or Map3DSystem.localserver.CachePolicy |
| *policy* |  |
| *urls* |  |
| *callbackFunc* | the call back function(entry, callbackContext or url) end will be called for each url in input urls. |
| *callbackContext* |  |
| *callbackProgressFunc* | this is an optional function that is called whenever a fraction of a url is downloaded
 the format is function(msg, callbackContext or url), where msg is {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number} |

---++++ !ResourceStore:CreateOrOpen

----------------------------------
 member functions: 
----------------------------------
 Initializes an instance and inserts rows in the Servers and Versions table of the DB if needed
   * _return_ __true__ : if succeed or nil if failed. 


__syntax__
<verbatim>function ResourceStore:CreateOrOpen(security_origin, name, required_cookie) </verbatim>


__parameters__

| *security* |  |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |
| *return* | if succeed or nil if failed. |

---++++ !ResourceStore:Open

 Initializes an instance from its server_id. Will not insert rows into
 the Servers or Versions table of the DB. If the expected rows are not
 present in the Servers and Versions table, this method fails and returns false.
   * _return_ __nil__ : if failed. true if succeed. 


__syntax__
<verbatim>function ResourceStore:Open(server_id)</verbatim>


__parameters__

| *server* |  |
| *id* |  |
| *return* | if failed. true if succeed. |

---++++ !ResourceStore:GetItem

 Gets an item from the store including or not the response body
   * _param_ __info__ :_only: If info_only is true, the response body of it is not retrieved.
   * _return_ __the__ : localserver.Item {entry, payload}is returned or nil if not found. 


__syntax__
<verbatim>function ResourceStore:GetItem(url, info_only)</verbatim>


__parameters__

| *url* |  |
| *info* | _only: If info_only is true, the response body of it is not retrieved. |
| *only* |  |

---++++ !ResourceStore:GetItemInfo

 Gets an item from the store without retrieving the response body


__syntax__
<verbatim>function ResourceStore:GetItemInfo(url)</verbatim>


__parameters__

| *url* |  |

---++++ !ResourceStore:DeleteAll

 Deletes all items in the store.
   * _return_ ____ : return true if succeed


__syntax__
<verbatim>function ResourceStore:DeleteAll() </verbatim>


__parameters__

| *return* | return true if succeed |

---++++ !ResourceStore:Delete

 Deletes a single item in the store.
   * _return_ ____ : return true if succeed


__syntax__
<verbatim>function ResourceStore:Delete(url) </verbatim>


__parameters__

| *url* |  |
| *return* | return true if succeed |

---++++ !ResourceStore:Rename

 Renames an item in  the store. If an item already exists for new_url, the pre-existing item is deleted.
   * _return_ ____ : return true if succeed


__syntax__
<verbatim>function ResourceStore:Rename(orig_url, new_url) </verbatim>


__parameters__

| *orig* |  |
| *url* |  |
| *new* |  |
| *url* |  |
| *return* | return true if succeed |

---++++ !ResourceStore:Copy

 Copies an item in  the store. If an item already exists for dst_url, the pre-existing item is deleted.


__syntax__
<verbatim>function ResourceStore:Copy(src_url, dst_url)</verbatim>


__parameters__

| *src* |  |
| *url* |  |
| *dst* |  |
| *url* |  |

---++++ !ResourceStore:IsCaptured

 Returns true if an item is captured for url.


__syntax__
<verbatim>function ResourceStore:IsCaptured(url)</verbatim>


__parameters__

| *url* |  |

---++++ !ResourceStore:GetCapturedFileName

 Returns the filename of a captured local file.
 return nil if failed, return empty string if not found.


__syntax__
<verbatim>function ResourceStore:GetCapturedFileName(url)</verbatim>


__parameters__

| *url* |  |

---++++ !ResourceStore:GetAllHeaders

 Returns all http headers for url


__syntax__
<verbatim>function ResourceStore:GetAllHeaders(url) </verbatim>


__parameters__

| *url* |  |

---++ ManagedResourceStore : public <localserver>
| *Title* | ManagedResourceStore : public <localserver> |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/25 |
| *File* | script/kids/3DMapSystemApp/localserver/ManagedResourceStore.lua |
---+++ Description
A ManagedResourceStore represents a set of entries in the WebCacheDB and allows the set to be managed as a group. 
The identifying properties of a LocalServer are its domain, name, required_cookie, and server_type.

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/ManagedResourceStore .lua");
</verbatim>

---+++ Member Functions

---++++ !ManagedResourceStore:new

<verbatim>------------------------------------------
 ManagedResourceStore  : public <localserver>
------------------------------------------
local ManagedResourceStore = commonlib.inherit(Map3DSystem.localserver.localserver, {
   -- type of WebCacheDB.ServerType
   server_type_ = WebCacheDB.ServerType.MANAGED_RESOURCE_STORE,

   -- default policy
   Cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 month"),
}</verbatim>);

commonlib.setfield("Map3DSystem.localserver.ManagedResourceStore", ManagedResourceStore);



__syntax__
<verbatim>function ManagedResourceStore:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !ManagedResourceStore:CreateOrOpen

----------------------------------
 public member functions: 
----------------------------------
 Initializes an instance and inserts rows in the Servers and Versions table of the DB if needed


__syntax__
<verbatim>function ManagedResourceStore:CreateOrOpen(security_origin, name, required_cookie) </verbatim>


__parameters__

| *security* |  |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |

---++++ !ManagedResourceStore:Open

 Initializes an instance from its server_id. Will not insert rows into
 the Servers or Versions table of the DB. If the expected rows are not
 present in the Servers and Versions table, this method fails and returns false.


__syntax__
<verbatim>function ManagedResourceStore:Open(server_id)</verbatim>


__parameters__

| *server* |  |
| *id* |  |

---++++ !ManagedResourceStore:GetManifestUrl

 Get the manifest url for this store
   * _param_ __manifest__ :_url: string
   * _return_ ____ : the manifest url (maybe ""), it returns nil if failed. 


__syntax__
<verbatim>function ManagedResourceStore:GetManifestUrl(manifest_url)</verbatim>


__parameters__

| *manifest* | _url: string |
| *url* |  |

---++++ !ManagedResourceStore:SetManifestUrl

 Sets the manifest url for this store
   * _param_ __manifest__ :_url: string


__syntax__
<verbatim>function ManagedResourceStore:SetManifestUrl(manifest_url)</verbatim>


__parameters__

| *manifest* | _url: string |
| *url* |  |

---++++ !ManagedResourceStore:HasVersion

 returns if the application has a version in the desired state or a version string. 
   * _param_ __state__ : it int, it is WebCacheDB.VersionReadyState, if string, it is the version string. 


__syntax__
<verbatim>function ManagedResourceStore:HasVersion(state) </verbatim>


__parameters__

| *state* | it int, it is WebCacheDB.VersionReadyState, if string, it is the version string. |

---++++ !ManagedResourceStore:GetUpdateInfo

 Retrieves the update info for this store
   * _param_ __return__ : status, last_time, manifest_date_header, update_error


__syntax__
<verbatim>function ManagedResourceStore:GetUpdateInfo() </verbatim>

---++++ !ManagedResourceStore:SetUpdateInfo

 Sets the update info for this applicaiton


__syntax__
<verbatim>function ManagedResourceStore:SetUpdateInfo(status, last_time, manifest_date_header, update_error) </verbatim>


__parameters__

| *status* |  |
| *last* |  |
| *time* |  |
| *manifest* |  |
| *date* |  |
| *header* |  |
| *update* |  |
| *error* |  |

---++ http constants
| *Title* | http constants |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/23 |
| *File* | script/kids/3DMapSystemApp/localserver/http_constants.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/http_constants.lua",
Map3DSystem.localserver.HttpConstants.DefaultSchemePortMapping
</verbatim>

---++ http cookies and related helper functions. 
| *Title* | http cookies and related helper functions.  |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/23 |
| *File* | script/kids/3DMapSystemApp/localserver/http_cookies.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/http_cookies.lua");
local CookieMap = Map3DSystem.localserver.CookieMap:new("www.paraengine.com/get.asmx?name=value&name2=value2")
</verbatim>

---+++ Member Functions

---++++ !CookieMap:new

<verbatim>--------------------------
 SecurityOrigin class
 Class that represents the origin of a URL. The origin includes the scheme, host, and port.
--------------------------
 A collection of cookie name and optional value pairs
local CookieMap = {
   -- an table of name to value map
   data = nil,
}</verbatim>;
commonlib.setfield("Map3DSystem.localserver.CookieMap", CookieMap);



__syntax__
<verbatim>function CookieMap:new(full_url)</verbatim>


__parameters__

| *full* |  |
| *url* |  |

---++++ !CookieMap:LoadMapForUrl

 Retrieves the cookies for the specified URL and populates the
 map with an entry for each value. Previous values in the map
 are cleared prior to loading the new values. If the cookie string
 cannot be retrieved, returns false and the map is not modified.
 Ex. Given "name=value;cookie" the map is populated as follows
     map["name"] = "value";
     map["cookie"] = "";
   * _param_ __url__ : string. 
   * _return_ ____ : Returns true if successful. Only "file","http", and "https" urls are supported. In the case of a file url, the host will be set to kUnknownDomain.


__syntax__
<verbatim>function CookieMap:LoadMapForUrl(url)</verbatim>


__parameters__

| *url* | string. |

---++++ !CookieMap:HasLocalServerRequiredCookie

 Returns true if the 'requiredCookie' attribute of a resource store is satisfied by the contents of this CookieMap. 
   * _param_ __required__ :_cookie: string. it can express either a particular cookie name/value pair, or the absence
 of cookie with a particular name.
 "foo=bar" --> a cookie name "foo" must have the value "bar"
 "foo" | "foo=" --> "foo" must be present but have an empty value
 "foo=;NONE;" --> the collection must not contain a cookie for "foo"


__syntax__
<verbatim>function CookieMap:HasLocalServerRequiredCookie(required_cookie)</verbatim>


__parameters__

| *required* | _cookie: string. it can express either a particular cookie name/value pair, or the absence
 of cookie with a particular name.
 "foo=bar" --> a cookie name "foo" must have the value "bar"
 "foo" | "foo=" --> "foo" must be present but have an empty value
 "foo=;NONE;" --> the collection must not contain a cookie for "foo" |
| *cookie* |  |

---++++ !CookieMap:GetCookie

 Retrieves the value of the cookie named 'cookie_name'. If the cookie
 is present but does not have a value, the value string will be empty.
   * _return_ __cookie__ :_vale


__syntax__
<verbatim>function CookieMap:GetCookie(cookie_name)</verbatim>


__parameters__

| *cookie* |  |
| *name* |  |
| *return* | _vale |

---++++ !CookieMap:HasCookie

   * _returns_ __true__ : if the map contains a cookie named 'cookie_name'


__syntax__
<verbatim>function CookieMap:HasCookie(cookie_name)</verbatim>


__parameters__

| *cookie* |  |
| *name* |  |
| *return* | if the map contains a cookie named 'cookie_name' |

---++++ !CookieMap:HasSpecificCookie

   * _return_ __true__ : if the map contains a cookie with 'cookie_name' having the value 'cookie_value'


__syntax__
<verbatim>function CookieMap:HasSpecificCookie(cookie_name, cookie_value)</verbatim>


__parameters__

| *cookie* |  |
| *name* |  |
| *cookie* |  |
| *value* |  |
| *return* | if the map contains a cookie with 'cookie_name' having the value 'cookie_value' |

---++++ !CookieMap.GetCookieString

 static public function: 
 Retrieves the cookies for the specified URL. Cookies are represented as
 strings of semi-colon or & delimited "name=value" pairs.
   * _return_ __the__ : string after ? separator in the url. it may return nil if no cookie string found


__syntax__
<verbatim>function CookieMap.GetCookieString(url)</verbatim>


__parameters__

| *url* |  |
| *return* | string after ? separator in the url. it may return nil if no cookie string found |

---++ URL security model
| *Title* | URL security model |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/22 |
| *File* | script/kids/3DMapSystemApp/localserver/security_model.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/security_model.lua");
local secureOrigin = Map3DSystem.localserver.SecurityOrigin:new()
</verbatim>

---+++ Member Functions

---++++ !SecurityOrigin:new

<verbatim>--------------------------
 SecurityOrigin class
 Class that represents the origin of a URL. The origin includes the scheme, host, and port.
--------------------------

local SecurityOrigin = {
   -- whether initialized from an URL
   initialized = false,
   -- string:  A url that contains the information representative of the security
   -- origin and nothing more. The path is always empty. The port number is
   -- not included for for the default port case. Eg. http://host:99, http://host
   url="",
   -- string: such as "http", "https", "file", if none is specified, it defaults to http. 
   scheme = "http",
   -- string: such as "www.paraengine.com"
   host,
   -- int: if nil it means the default port for the scheme, such as 80 for http. 
   port,
   -- string: it is tostring(port)
   port_string,
   -- private: string:  The full url the origin was initialized with. This should be removed in future. 
   full_url,
}</verbatim>;

commonlib.setfield("Map3DSystem.localserver.SecurityOrigin", SecurityOrigin);



__syntax__
<verbatim>function SecurityOrigin:new(full_url)</verbatim>


__parameters__

| *full* |  |
| *url* |  |

---++++ !SecurityOrigin:InitFromUrl

 Extacts the scheme, host, and port of the 'full_url'.
   * _param_ __full__ :_url: string. 
   * _return_ ____ : Returns true if successful. Only "file","http", and "https" urls are supported. In the case of a file url, the host will be set to kUnknownDomain.


__syntax__
<verbatim>function SecurityOrigin:InitFromUrl(full_url)</verbatim>


__parameters__

| *full* | _url: string. |
| *url* |  |

---++++ !SecurityOrigin:IsSameOrigin

   * _param_ __other__ : another instance of SecurityOrigin or the full url string of another security origin
   * _return_ ____ : true if 'other' and 'this' represent the same origin. If either origin is not initalized, returns false. 


__syntax__
<verbatim>function SecurityOrigin:IsSameOrigin(other)</verbatim>


__parameters__

| *other* | another instance of SecurityOrigin or the full url string of another security origin |

---++ some utility functions for making URLs
| *Title* | some utility functions for making URLs |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/22 |
| *File* | script/kids/3DMapSystemApp/localserver/UrlHelper.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/UrlHelper.lua");
Map3DSystem.localserver.UrlHelper.WS_to_REST("www.paraengine.com/getPos.asmx", {uid=123, pos = {x=1, y=2}}, {"uid", "pos.x", "pos.y"});
Map3DSystem.localserver.UrlHelper.BuildURLQuery("profile.html", {uid=123, show=true});
Map3DSystem.localserver.UrlHelper.IsDefaultPort("http", 80)
</verbatim>

---+++ Member Functions

---++++ !UrlHelper.WS_to_REST

 converting a web service request to a REST-like url. (REST stands for RESTFUL web)
   * _param_ __wsUrl__ : web service url, e.g. "www.paraengine.com/getPos.asmx"
   * _param_ __msg__ : the input msg table of the web service. e.g. {uid=123, pos = {x=1, y=2}}
   * _param_ __fields__ : an array of text fields in msg. it may contain dot for depth child names. e.g. {"uid", "pos.x", "pos.y"}
   * _return_ ____ : a unique url is returned, encoding all web service input to a REST url. 
 in the above case, it is "www.paraengine.com/getPos.asmx?uid=123&pos.x=1&pos.y=2"


__syntax__
<verbatim>function UrlHelper.WS_to_REST(wsUrl, msg, fields)</verbatim>


__parameters__

| *wsUrl* | web service url, e.g. "www.paraengine.com/getPos.asmx" |
| *msg* |  |
| *fields* | an array of text fields in msg. it may contain dot for depth child names. e.g. {"uid", "pos.x", "pos.y"} |

---++++ !UrlHelper.BuildURLQuery

 Use: NPL.EncodeURLQuery instead if you want encoded url query that can be feed directly to a rest call. 
 build url query string. should sort in alphabetic order
   * _param_ __baseUrl__ : base url such as "paraengine.com/index.aspx"
   * _param_ __params__ : name, value pairs , such as {id=10, time=20}
   * _return_ ____ : a unique url is returned such as "paraengine.com/index.aspx?id=10&time=20"


__syntax__
<verbatim>function UrlHelper.BuildURLQuery(baseUrl, params)</verbatim>


__parameters__

| *baseUrl* | base url such as "paraengine.com/index.aspx" |
| *params* |  |
| *return* | a unique url is returned such as "paraengine.com/index.aspx?id=10&time=20" |

---++++ !UrlHelper.IsWebSerivce

 return true if the url is for a web service. 


__syntax__
<verbatim>function UrlHelper.IsWebSerivce(url)</verbatim>


__parameters__

| *url* |  |

---++++ !UrlHelper.IsWebPage

 return true if the url is for a web page request, such as RSS feed, HTML, xml, or http REST call. 


__syntax__
<verbatim>function UrlHelper.IsWebPage(url)</verbatim>


__parameters__

| *url* |  |

---++++ !UrlHelper.IsFileUrl

 return true if the url is for a file request, such as zip, jpg, png, etc 


__syntax__
<verbatim>function UrlHelper.IsFileUrl(url)</verbatim>


__parameters__

| *url* |  |

---++++ !UrlHelper.IsDefaultPort

   * _param_ __scheme__ : string "http", "https", "file"
   * _param_ __port__ : int. 80
   * _return_ __true__ : if mapped. 


__syntax__
<verbatim>function UrlHelper.IsDefaultPort(scheme, port) </verbatim>


__parameters__

| *scheme* | string "http", "https", "file" |
| *port* |  |
| *return* | if mapped. |

---++++ !UrlHelper.IsStringValidPathComponent

-----------------------------------------
 string utility functions
-----------------------------------------

 Returns true if and only if the entire string (other than terminating null)
 consists entirely of characters meeting the following criteria:
 - visible ASCII
 - None of the following characters: / \ : * ? " < > | ; ,
 - Doesn't start with a dot.
 - Doesn't end with a dot.


__syntax__
<verbatim>function UrlHelper.IsStringValidPathComponent(s)</verbatim>


__parameters__

| *s* |  |

---++++ !UrlHelper.EnsureStringValidPathComponent

   * _return_ __a__ : modified string, replacing characters that are not valid in a file path
 component with the '_' character. Also replaces leading and trailing dots with the '_' character
 See IsCharValidInPathComponent


__syntax__
<verbatim>function UrlHelper.EnsureStringValidPathComponent(s) </verbatim>


__parameters__

| *s* |  |
| *return* | modified string, replacing characters that are not valid in a file path
 component with the '_' character. Also replaces leading and trailing dots with the '_' character
 See IsCharValidInPathComponent |

---++++ !UrlHelper.url_decode

 UNTESTED: Decode an URL-encoded string
 (Note that you should only decode a URL string after splitting it; this allows you to correctly process quoted "?" characters in the query string or base part, for instance.) 


__syntax__
<verbatim>function UrlHelper.url_decode(str)</verbatim>


__parameters__

| *str* |  |

---++++ !UrlHelper.url_encode

 UNTESTED: URL-encode a string


__syntax__
<verbatim>function UrlHelper.url_encode(str)</verbatim>


__parameters__

| *str* |  |

---++++ !UrlHelper.url_getparams

 get request url parameter by its name. for example if page url is "www.paraengine.com/user?id=10&time=20", then GetRequestParam("id") will be "10".
   * _param_ __request__ :_url: url to from which to get parameters 
   * _param_ __paramName__ : parameter name. 
   * _return_ ____ : nil or string value.


__syntax__
<verbatim>function UrlHelper.url_getparams(request_url, paramName)</verbatim>


__parameters__

| *request* | _url: url to from which to get parameters |
| *url* |  |
| *paramName* |  |
| *return* | nil or string value. |

---++++ !UrlHelper.ValidateEmailAddress

 UNTESTED: Match Email addresses


__syntax__
<verbatim>function UrlHelper.ValidateEmailAddress(email)</verbatim>


__parameters__

| *email* |  |

---++ Some header definition and functions for WebCacheDB. 
| *Title* | Some header definition and functions for WebCacheDB.  |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/22 |
| *File* | script/kids/3DMapSystemApp/localserver/WebCacheDB_def.lua |
---+++ Description
Only included by the WebCacheDB.lua. it just make the file easy to read by splitting it to multiple files. 

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/WebCacheDB_def.lua");
</verbatim>

---+++ Member Functions

---++++ !ServerInfo:new

<verbatim>-----------------------------
 attributes
-----------------------------
 the name of the local server database file
WebCacheDB.kFileName = "Database/localserver.db";
 LXZ:2008.12.16: change WebCacheDB.kCurrentVersion to automatically upgrade db
WebCacheDB.kVersionFileName = "Database/localserver.ver";

 whether to use lazy writing, when lazy writing is enabled, we will not commit to database immediately, but will batch many commit in a single Flush. 
 it will increase the speed by 100 times, if we have many mini transactions to deal with. It is highly recommended to turn this on. 
WebCacheDB.EnableLazyWriting = true;
 after how many milliseconds the lazy writing will flush transactions to datebase, when there are no more transactions comming. 
WebCacheDB.AutoFlushInterval = 10000;

WebCacheDB.ServerType = {
    MANAGED_RESOURCE_STORE = 0,
    RESOURCE_STORE = 1,
    WEBSERVICE_STORE = 2,
    URLRESOURCE_STORE = 3,
};

WebCacheDB.VersionReadyState = {
    VERSION_DOWNLOADING = 0,
    VERSION_CURRENT = 1
};

 current server state
WebCacheDB.UpdateStatus = {
    UPDATE_OK = 0,
    UPDATE_CHECKING = 1,
    UPDATE_DOWNLOADING = 2,
    UPDATE_FAILED = 3
};

-----------------------------
 WebCacheDB.ServerInfo class
-----------------------------
 a server is a set of dynamic or static web entries that are managed as a group. 
 entries in a group usually shares the same server settings like minUpdateTime, etc. 
local ServerInfo = {
   -- int64 server id. 
   id = nil,
   -- temporarily enable or disable this server. 
    enabled = true,
    -- string: e.g. "www.paraengine.com"
    security_origin_url = "",
    -- string: server resource store name. e.g. "MyAppName"
    name = "",
    -- string: format same as http requery string. e.g."name=value&name2=value2"
    required_cookie = "",
    -- type of WebCacheDB.ServerType
    server_type = WebCacheDB.ServerType.RESOURCE_STORE,
    -- string: only used when server_type is MANAGED_RESOURCE_STORE, where the server represent 
    -- a static collection of web entries defined in the manifest file. 
    manifest_url = nil,
    -- type of WebCacheDB.UpdateStatus
    update_status = WebCacheDB.UpdateStatus.UPDATE_OK,
    -- string
    last_error_message=nil,
    -- int64
    last_update_check_time=0,
    -- string
    manifest_date_header=nil,
}</verbatim>
WebCacheDB.ServerInfo = ServerInfo;



__syntax__
<verbatim>function ServerInfo:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !VersionInfo:new

<verbatim>-----------------------------
 WebCacheDB.VersionInfo class
-----------------------------
 an URL resource may has be a version that is already downloaded, while having another newer version being downloaded. 
 Hence, the same url has two version states. One can access the downloaded version while a newer version is being downloaded. 
 usually after the newer version is downloaded, the old version is deleted, so that there is only one downloaded version left in the db thereafterwards. 
local VersionInfo = {
   -- int64
    id,
    -- int64
    server_id = 0,
    -- string
    version_string="",
    -- WebCacheDB.VersionReadyState
    ready_state = WebCacheDB.VersionReadyState.VERSION_DOWNLOADING,
    -- string
    session_redirect_url="",
}</verbatim>;

WebCacheDB.VersionInfo = VersionInfo; 


__syntax__
<verbatim>function VersionInfo:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !EntryInfo:new

<verbatim>-----------------------------
 WebCacheDB.EntryInfo class
-----------------------------
 an URL web resource entry
local EntryInfo = {
   -- int64 
   id,
   -- int64 
    version_id,
    -- string
    url="",
    -- string
    src,
    -- string
    redirect = nil,
    ignore_query = false,
    -- int64 
    payload_id = nil,
}</verbatim>;

WebCacheDB.EntryInfo = EntryInfo; 


__syntax__
<verbatim>function EntryInfo:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !PayloadInfo:new

<verbatim>-----------------------------
 WebCacheDB.PayloadInfo class
-----------------------------
 the body data of the web resource entry
local PayloadInfo = {
   -- int64 
   id,
   -- int64 
    creation_date = 0,
    -- int: see Map3DSystem.localserver.HttpConstants. Default to HTTP_OK
    status_code = 200,
    -- string
    status_line = nil,
    -- string: Must be terminated with a blank line
    headers = nil,
    ---------------------------------
    -- The following fields are empty for info_only queries
    ---------------------------------
    -- the cached file path that contains the body data. Only applicable to file type urls. 
    cached_filepath = nil,
    -- the body response data itself. Only applicable to webservices where the response is stored as strings in the database instead of local file system. 
    data = nil,
    is_synthesized_http_redirect = false,
}</verbatim>;

WebCacheDB.PayloadInfo = PayloadInfo; 


__syntax__
<verbatim>function PayloadInfo:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !PayloadInfo:GetHeader

 Returns a particular header value. may return nil if not found. 


__syntax__
<verbatim>function PayloadInfo:GetHeader(name)</verbatim>


__parameters__

| *name* |  |

---++++ !PayloadInfo:GetMsgData

 this function is assumed that the member data is a message table possible from the reponse of a web service.
   * _return_ __the__ : self.data as a table. 


__syntax__
<verbatim>function PayloadInfo:GetMsgData()</verbatim>


__parameters__

| *return* | self.data as a table. |

---++++ !WebCacheDB:Init

<verbatim> SQL create table command columns
WebCacheDB.kWebCacheTables =
{
   { table_name = WebCacheDB.kServersTable,
   columns = [[
   (ServerID INTEGER PRIMARY KEY AUTOINCREMENT,
   Enabled INT CHECK(Enabled IN (0, 1)),
   SecurityOriginUrl TEXT NOT NULL,
   Name TEXT NOT NULL,
   RequiredCookie TEXT,
   ServerType INT CHECK(ServerType IN (0, 1 , 2, 3)),
   ManifestUrl TEXT,
   UpdateStatus INT CHECK(UpdateStatus IN (0,1,2,3)),
   LastUpdateCheckTime INTEGER DEFAULT 0,
   ManifestDateHeader TEXT,
   LastErrorMessage TEXT)]]},

   { table_name = WebCacheDB.kVersionsTable,
   columns = [[
   (VersionID INTEGER PRIMARY KEY AUTOINCREMENT,
   ServerID INTEGER NOT NULL,
   VersionString TEXT NOT NULL,
   ReadyState INTEGER CHECK(ReadyState IN (0, 1)),
   SessionRedirectUrl TEXT)]]},
   
   -- src is The manifest file entry's src attribute
   { table_name = WebCacheDB.kEntriesTable,
   columns = [[
   (EntryID INTEGER PRIMARY KEY AUTOINCREMENT,
   VersionID INTEGER,
   Url TEXT NOT NULL,
   Src TEXT, 
   PayloadID INTEGER,
   Redirect TEXT,
   IgnoreQuery INTEGER CHECK(IgnoreQuery IN (0, 1)))]]},

   { table_name = WebCacheDB.kPayloadsTable,
   columns = [[
   (PayloadID INTEGER PRIMARY KEY AUTOINCREMENT,
   CreationDate INTEGER,
   Headers TEXT,
   StatusCode INTEGER,
   StatusLine TEXT)]]},

   -- BodyID is the same ID as the payloadID
   -- With USE_FILE_STORE, bodies are stored as discrete files, otherwise as blobs in the DB
   { table_name = WebCacheDB.kResponseBodiesTable,
   columns = [[
   (BodyID INTEGER PRIMARY KEY, 
   FilePath TEXT, 
   Data BLOB)]]},    
}</verbatim>;

WebCacheDB.kSchemaVersionName = "version";
WebCacheDB.kSchemaBrowserName = "browser";
 The values stored in the system_info table
WebCacheDB.kCurrentVersion = 2;
WebCacheDB.kCurrentBrowser = "NPL";

 sql db object. 
WebCacheDB._db = nil;
 how many queued(uncommitted) transactions are there, if lazy writing is used. 
WebCacheDB.queued_transaction_count = 0;

 create open database


__syntax__
<verbatim>function WebCacheDB:Init()</verbatim>

---++++ !WebCacheDB:Flush

 flush all transactions to database. 


__syntax__
<verbatim>function WebCacheDB:Flush()</verbatim>

---++++ !WebCacheDB:CreateOrUpgradeDatabase

 currently only supporting creating a new database. 


__syntax__
<verbatim>function WebCacheDB:CreateOrUpgradeDatabase()</verbatim>

---++++ !WebCacheDB:CreateTables

 create tables in the database 


__syntax__
<verbatim>function WebCacheDB:CreateTables()</verbatim>

---++++ !WebCacheDB:Begin

-------------------------------------
 database transaction related functions
-------------------------------------

 private: 
WebCacheDB.transaction_count_ = 0
WebCacheDB.transaction_labels_ = {}

 begin transaction: it emulates nested transactions. 
 lazy writing is employed (which means that we do not commit changes immediately)
   * _param_ __label__ : nil or a string label for debugging purposes


__syntax__
<verbatim>function WebCacheDB:Begin(label)</verbatim>


__parameters__

| *label* | nil or a string label for debugging purposes |

---++++ !WebCacheDB:End

   * _param_ __bRollback__ : if true, it will rollback on last root pair. 
 end transaction


__syntax__
<verbatim>function WebCacheDB:End(bRollback)</verbatim>


__parameters__

| *bRollback* | if true, it will rollback on last root pair. 
 end transaction |

---++++ !WebCacheDB:MaybeInitiateUpdateTask

-------------------------------
 common functions:
-------------------------------


__syntax__
<verbatim>function WebCacheDB:MaybeInitiateUpdateTask()</verbatim>

---++ the local server's db provider interface.
| *Title* | the local server's db provider interface. |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/21 |
| *File* | script/kids/3DMapSystemApp/localserver/WebCacheDB.lua |
---+++ Description
This class provides a data access API for web capture data. The underlying repository is SQLite. This class encaplates the SQL required to insert, update, and delete records into the database.
Note: the interface resambles the google gear's localserver interface.
Usage: when calling paraworld API's webservice, one can assume that u can call them as often as you want and either online or offline. The local server app is developed, 
so that the app like the map does not need to have its own local db mirror, it just calls web services each time it wants something. 

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/WebCacheDB.lua");
local webDB = Map3DSystem.localserver.WebCacheDB.GetDB()
</verbatim>

---+++ Member Functions

---++++ !WebCacheDB.GetDB

 get the singleton instance of this database file. It will initialize the db if it is not yet initialized. 
 Note: An instance of this class can only be accessed from a single thread.


__syntax__
<verbatim>function WebCacheDB.GetDB()</verbatim>

---++++ !WebCacheDB:CanService

-------------------------------
 resource service functions
-------------------------------
 Returns if the database has a response for the url at this time
   * _param_ __url__ : string
   * _return_ __boolean__ :.


__syntax__
<verbatim>function WebCacheDB:CanService(url)</verbatim>


__parameters__

| *url* | string |

---++++ !WebCacheDB:Service

 Returns a response for the url at this time, if head_only is requested
 the payload's data will not be populated
   * _param_ __url__ : string
   * _param_ __head__ :_only: boolean
   * _param_ __payload__ : in|out. if nil, a new one is created. type of WebCacheDB.PayloadInfo
   * _return_ __boolean__ :, PayloadInfo . the first return value is true if succeed. 


__syntax__
<verbatim>function WebCacheDB:Service(url, head_only, payload)</verbatim>


__parameters__

| *url* | string |
| *head* |  |
| *only* |  |
| *payload* | in|out. if nil, a new one is created. type of WebCacheDB.PayloadInfo |

---++++ !WebCacheDB:Service_payloadID

 return the payload ID for a given url. 
   * _param_ __url__ : the url for which we are servicing. 
  content after fragment identifier # is always ignored. 
  content of query paramter ? is ignored only if there is no matching entry with the query string included.
   * _return_ __payloadID__ :  
 TODO: lxz: a redirectUrl may be returned, If we found an entry that requires a cookie, and no cookie exists, and
   specifies a redirect url for use in that case, then return the redirect url.


__syntax__
<verbatim>function WebCacheDB:Service_payloadID(url)</verbatim>


__parameters__

| *url* | the url for which we are servicing. 
  content after fragment identifier # is always ignored. 
  content of query paramter ? is ignored only if there is no matching entry with the query string included. |

---++++ !WebCacheDB:FindPayload

-------------------------------
 payload related functions
-------------------------------

 read from server database table row to PayloadInfo struct. 
local function ReadPayloadInfo(row, payload)
   payload.id = row.PayloadID;
   payload.creation_date = row.CreationDate;
   payload.headers = row.Headers;
   payload.status_line = row.StatusLine;
   payload.status_code = row.StatusCode;
end

 Returns the payload with the given payload_id. 
   * _param_ __payload__ :_id: int64
   * _param_ __info__ :_only: if info_only is true, the data (response body) and cached_filepath fields will be empty
   * _param_ __payload__ : in|out. if nil, a new one is created. type of WebCacheDB.PayloadInfo
   * _return_ __payload__ :. the payload is returned or nil if failed. 


__syntax__
<verbatim>function WebCacheDB:FindPayload(payload_id, info_only, payload)</verbatim>


__parameters__

| *payload* | in|out. if nil, a new one is created. type of WebCacheDB.PayloadInfo |
| *id* |  |
| *info* |  |
| *only* |  |
| *payload* | in|out. if nil, a new one is created. type of WebCacheDB.PayloadInfo |

---++++ !WebCacheDB:InsertPayload

 insert payload to db 


__syntax__
<verbatim>function WebCacheDB:InsertPayload(server_id, url, payload) </verbatim>


__parameters__

| *server* |  |
| *id* |  |
| *url* |  |
| *payload* |  |

---++++ !WebCacheDB:MaybeDeletePayload

 only delete an payload if there is no entry referencing it. 


__syntax__
<verbatim>function WebCacheDB:MaybeDeletePayload(payload_id) </verbatim>


__parameters__

| *payload* |  |
| *id* |  |

---++++ !WebCacheDB:DeletePayload

 delete an payload by its id. 


__syntax__
<verbatim>function WebCacheDB:DeletePayload(payload_id)</verbatim>


__parameters__

| *payload* |  |
| *id* |  |

---++++ !WebCacheDB:DeleteUnreferencedPayloads

 delete all payload that are not referenced by any entry. 


__syntax__
<verbatim>function WebCacheDB:DeleteUnreferencedPayloads() </verbatim>

---++++ !WebCacheDB:FindServer

-------------------------------
 server related functions
-------------------------------

 read from server database table row to ServerInfo struct. 
local function ReadServerInfo(row, server)
   server.id = row.ServerID;
   server.enabled = (row.Enabled == 1);
   server.security_origin_url = row.SecurityOriginUrl;
   server.name = row.Name;
   server.required_cookie = row.RequiredCookie;
   server.server_type = row.ServerType;
   server.manifest_url = row.ManifestUrl;
   server.update_status = row.UpdateStatus;
   server.last_update_check_time = row.LastUpdateCheckTime;
   server.manifest_date_header = row.ManifestDateHeader;
   server.last_error_message = row.LastErrorMessage;
end

 Returns server info for the given server_id
   * _param_ __server__ :_id: int64, if nil the third to sixth parameters are used
   * _param_ __server__ : in|out. if nil, a new one is created and returned. type of WebCacheDB.ServerInfo
   * _param_ __security__ :_origin, name, required_cookie, server_type: in case server_id is nil, these parameters are used together to find a server.
   * _return_ __server__ :.  or nil if failed


__syntax__
<verbatim>function WebCacheDB:FindServer(server_id, server, security_origin, name, required_cookie, server_type)</verbatim>


__parameters__

| *server* | _id: int64, if nil the third to sixth parameters are used |
| *id* |  |
| *server* | _id: int64, if nil the third to sixth parameters are used |
| *security* | _origin, name, required_cookie, server_type: in case server_id is nil, these parameters are used together to find a server. |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |
| *server* | _id: int64, if nil the third to sixth parameters are used |
| *type* |  |

---++++ !WebCacheDB:FindServersForOrigin

 return a list of servers having the same origin
   * _param_ __security__ :_origin: type of Map3DSystem.localserver.SecurityOrigin or an URL string
   * _return_ ____ : an array of ServerInfo is returned. 


__syntax__
<verbatim>function WebCacheDB:FindServersForOrigin(security_origin) </verbatim>


__parameters__

| *security* | _origin: type of Map3DSystem.localserver.SecurityOrigin or an URL string |
| *origin* |  |

---++++ !WebCacheDB:InsertServer

 Inserts a new row into the Servers table. The id field of the server
 parameter is updated with the id of the inserted row.
   * _param_ __server__ : type of ServerInfo
   * _return_ __nil__ : if failed, or server object. 


__syntax__
<verbatim>function WebCacheDB:InsertServer(server)</verbatim>


__parameters__

| *server* | type of ServerInfo |

---++++ !WebCacheDB:DeleteServersForOrigin

 Deletes all servers and associated data for the given origin


__syntax__
<verbatim>function WebCacheDB:DeleteServersForOrigin(origin) </verbatim>


__parameters__

| *origin* |  |

---++++ !WebCacheDB:DeleteServer

 Deletes the Server row and all related versions and entries and no longer referenced payloads.
   * _param_ __id__ : server id. 
   * _return_ __true__ : if succeed


__syntax__
<verbatim>function WebCacheDB:DeleteServer(id)</verbatim>


__parameters__

| *id* | server id. |

---++++ !WebCacheDB:UpdateServer

 update server according to the second parameter type, see local functions inside. 


__syntax__
<verbatim>function WebCacheDB:UpdateServer(id, ...)</verbatim>


__parameters__

| *id* |  |

---++++ !WebCacheDB:InsertVersion

----------------------------
 version related. 
----------------------------

 translate database row to version info struct. 
local function ReadVersionInfo(row, version)
   version.id = row.VersionID;
   version.server_id = row.ServerID;
   version.version_string = row.VersionString;
   version.ready_state = row.ReadyState;
   version.session_redirect_url = row.SessionRedirectUrl;
end

 Inserts a new row into the Versions table. The id field of the version
 parameter is updated with the id of the inserted row.
   * _param_ __version__ : type of VersionInfo
   * _return_ ____ : return nil if failed and true if succeed. 


__syntax__
<verbatim>function WebCacheDB:InsertVersion(version) </verbatim>


__parameters__

| *version* | type of VersionInfo |

---++++ !WebCacheDB:FindVersion

 Returns the version info for the given server_id and ready_state|version_string
   * _param_ __server__ :_id
   * _param_ __arg1__ : ready_state or version_string
   * _return_ __version__ : info or nil if failed. 


__syntax__
<verbatim>function WebCacheDB:FindVersion(server_id, arg1)</verbatim>


__parameters__

| *server* | _id |
| *id* |  |
| *arg1* |  |
| *return* | info or nil if failed. |

---++++ !WebCacheDB:FindVersions

 Returns an array of version info for all versions associated with the given server_id
   * _param_ __server__ :_id
   * _return_ ____ : an array of VersionInfo is returned. or empty table if no one is found. 


__syntax__
<verbatim>function WebCacheDB:FindVersions(server_id) </verbatim>


__parameters__

| *server* | _id |
| *id* |  |

---++++ !WebCacheDB:UpdateVersion

 Updates the ReadyState column for the given version_id
   * _param_ __id__ : version id
   * _param_ __ready__ :_state: 0|1 or WebCacheDB.VersionReadyState


__syntax__
<verbatim>function WebCacheDB:UpdateVersion(id, ready_state) </verbatim>


__parameters__

| *id* | version id |
| *ready* |  |
| *state* |  |

---++++ !WebCacheDB:DeleteVersion

 Deletes the Version row and all related entries and no longer referenced payloads


__syntax__
<verbatim>function WebCacheDB:DeleteVersion(version_id)</verbatim>


__parameters__

| *version* |  |
| *id* |  |

---++++ !WebCacheDB:DeleteVersions

 Deletes the Version row and all related entries and no longer referenced payloads


__syntax__
<verbatim>function WebCacheDB:DeleteVersions(arg1)</verbatim>


__parameters__

| *arg1* |  |

---++++ !ReadEntryInfo

----------------------------------------
 entries related functions. 
----------------------------------------
 translate from database row to EntryInfo struct.


__syntax__
<verbatim>function ReadEntryInfo(row, entry)</verbatim>


__parameters__

| *row* |  |
| *entry* |  |

---++++ !WebCacheDB:InsertEntry

 Inserts a new row into the Entries table. The id field of the entry
 parameter is updated with the id of the inserted row.
   * _param_ __entry__ : type of EntryInfo
   * _return_ __true__ : if succeed;


__syntax__
<verbatim>function WebCacheDB:InsertEntry(entry) </verbatim>


__parameters__

| *entry* | type of EntryInfo |

---++++ !WebCacheDB:DeleteEntries

 Deletes all entries with the given version_id|version_ids. Does not fail if there are no matching entries.
   * _param_ __arg1__ : version_id or an array of version_ids


__syntax__
<verbatim>function WebCacheDB:DeleteEntries(arg1)</verbatim>


__parameters__

| *arg1* | version_id or an array of version_ids |

---++++ !WebCacheDB:DeleteEntry2

 Deletes the entry with the given version_id and url. Does not fail if there is no matching entry.


__syntax__
<verbatim>function WebCacheDB:DeleteEntry2(version_id, url)</verbatim>


__parameters__

| *version* |  |
| *id* |  |
| *url* |  |

---++++ !WebCacheDB:FindEntry

 Returns the entry for the given version_id and url


__syntax__
<verbatim>function WebCacheDB:FindEntry(version_id, url) </verbatim>


__parameters__

| *version* |  |
| *id* |  |
| *url* |  |

---++++ !WebCacheDB:FindEntriesHavingNoResponse

 Returns an array of entries for version_id that do no have an associated payload or a redirect specified.


__syntax__
<verbatim>function WebCacheDB:FindEntriesHavingNoResponse(version_id) </verbatim>


__parameters__

| *version* |  |
| *id* |  |

---++++ !WebCacheDB:CountEntries

 Counts the number of entries for the given version_id. nil is returned if failed.


__syntax__
<verbatim>function WebCacheDB:CountEntries(version_id) </verbatim>


__parameters__

| *version* |  |
| *id* |  |

---++++ !WebCacheDB:UpdateEntry

 Updates the entry for the given version_id and orig_url to associate
 it with new_url. Does not fail if there is no matching orig entry.


__syntax__
<verbatim>function WebCacheDB:UpdateEntry(version_id, orig_url, new_url) </verbatim>


__parameters__

| *version* |  |
| *id* |  |
| *orig* |  |
| *url* |  |
| *new* |  |
| *url* |  |

---++++ !WebCacheDB:UpdateEntriesWithNewPayload

 Updates all entries for the given version_id and url (or src) to
 associate them with the given payload_id and redirect_url.


__syntax__
<verbatim>function WebCacheDB:UpdateEntriesWithNewPayload(version_id, url,payload_id, redirect_url) </verbatim>


__parameters__

| *version* |  |
| *id* |  |
| *url* |  |
| *payload* |  |
| *id* |  |
| *redirect* |  |
| *url* |  |

---++ A WebCacheDB_Store is partial implementation of WebCacheDB to store the response bodies in the database
| *Title* | A WebCacheDB_Store is partial implementation of WebCacheDB to store the response bodies in the database |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/23 |
| *File* | script/kids/3DMapSystemApp/localserver/WebCacheDB_store.lua |
---+++ Description
-- A WebCacheBlobStore is used by a WebCacheDB to store the response
-- bodies in the SQLite database as blobs. At this time, all HTTP post is stored as flat files in the
-- file system and all web service responses are stored in database as the blob data
-- This file is only used by WebCacheDB

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/WebCacheDB_store.lua");
</verbatim>

---+++ Member Functions

---++++ !WebCacheDB:InsertBody

 data directory where to store temporary local server files. 
WebCacheDB.dataDir_ = "temp/webcache"


 Inserts a response body into the store


__syntax__
<verbatim>function WebCacheDB:InsertBody(server_id, url, payload)</verbatim>


__parameters__

| *server* |  |
| *id* |  |
| *url* |  |
| *payload* |  |

---++++ !WebCacheDB:ReadBody

 Reads a body from the store
   * _param_ __payload__ : in|out table
   * _param_ __info__ :_only: boolean
   * _return_ __payload__ : is returned.  


__syntax__
<verbatim>function WebCacheDB:ReadBody(payload, info_only)</verbatim>


__parameters__

| *payload* | in|out table |
| *info* |  |
| *only* |  |
| *return* | is returned. |

---++++ !WebCacheDB:DeleteBody

 Deletes a body from the store


__syntax__
<verbatim>function WebCacheDB:DeleteBody(payload_id)</verbatim>


__parameters__

| *payload* |  |
| *id* |  |

---++++ !WebCacheDB.GetDataDirectory

--------------------------------
 file store related 
--------------------------------
 get directory name for a given security origin. 
   * _param_ __origin__ : securityOrigin object. 
   * _param_ __path__ : path of base directory. if nil, it will use WebCacheDB.dataDir_


__syntax__
<verbatim>function WebCacheDB.GetDataDirectory(origin, path)</verbatim>


__parameters__

| *origin* | securityOrigin object. |
| *path* |  |

---++++ !WebCacheDB:GetDirectoryPathForServer

 Note: it ends with "/"
 return the full path of the directory containing files associated with server_id. 


__syntax__
<verbatim>function WebCacheDB:GetDirectoryPathForServer(server_id)</verbatim>


__parameters__

| *server* |  |
| *id* |  |

---++++ !WebCacheDB:CreateDirectoryForServer

 Creates a directory to contain the files associated with server_id. 


__syntax__
<verbatim>function WebCacheDB:CreateDirectoryForServer(server_id)</verbatim>


__parameters__

| *server* |  |
| *id* |  |

---++ partial implementation of WebCacheDB for security origin permissions
| *Title* | partial implementation of WebCacheDB for security origin permissions |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/24 |
| *File* | script/kids/3DMapSystemApp/localserver/WebCacheDB_permissions.lua |
---+++ Description
generally, it verifies if an url security origin can be serviced. 
A white url list and a black url list can be edited in this file or added dynamically at runtime. 
Currently, it allows all http request. 

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/WebCacheDB_permissions.lua");
</verbatim>

---+++ Member Functions

---++++ !WebCacheDB:IsOriginAllowed

<verbatim> url in the white list is always serviced
 format is identical to regular expression as in string.find. 
local whiteList = {
   -- currently we allow all http urls. 
   "http://",
}

 url in the black list is always blocked, 
 format is identical to regular expression as in string.find. see examples below
local blackList = {
   -- "192%.168%.0%.100",
   -- "192.*",
   -- "https://*.",
   -- "http://[^:]:%d+",
   -- "http://[^:]:60001",
}</verbatim>

 whether the given url's securtiy origin is allowed. 
   * _param_ __securityOrigin__ : type of Map3DSystem.localserver.SecurityOrigin or an URL string
   * _return_ __boolean__ :


__syntax__
<verbatim>function WebCacheDB:IsOriginAllowed(securityOrigin)</verbatim>


__parameters__

| *securityOrigin* | type of Map3DSystem.localserver.SecurityOrigin or an URL string |

---++ helper functions of sql database. 
| *Title* | helper functions of sql database.  |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/21 |
| *File* | script/kids/3DMapSystemApp/localserver/sqldb_wrapper.lua |
---+++ Description


%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/sqldb_wrapper.lua");
Map3DSystem.localserver.SqlDb.DropAllObjects(_db)
local table = Map3DSystem.localserver.NameValueTable:new(_db, "MyTable");
table:MaybeCreateTable();
</verbatim>

---+++ Member Functions

---++++ !SqlDb.DropAllObjects

 drop all tables in the given database. 


__syntax__
<verbatim>function SqlDb.DropAllObjects(_db)</verbatim>


__parameters__

| *db* |  |

---++++ !NameValueTable:new

<verbatim>----------------------------
 a table with just name value pairs. 
----------------------------
local NameValueTable = 
{
   -- A pointer to the SQLDatabase our table will be created in.
   _db, 
   -- The name of the table we will be storing name/value pairs in.
   table_name,
}</verbatim>
Map3DSystem.localserver.NameValueTable = NameValueTable;

 Creates an instance for the specified database and table name.


__syntax__
<verbatim>function NameValueTable:new(db, table_name)</verbatim>


__parameters__

| *db* |  |
| *table* |  |
| *name* |  |

---++++ !NameValueTable:MaybeCreateTable

 Creates the table if it doesn't already exist.


__syntax__
<verbatim>function NameValueTable:MaybeCreateTable()</verbatim>

---++ base class for local server (ResourceStores and ManagedResourceStores)
| *Title* | base class for local server (ResourceStores and ManagedResourceStores) |
| *Author(s)* | LiXizhi |
| *Date* | 2008/2/25 |
| *File* | script/kids/3DMapSystemApp/localserver/localserver.lua |
---+++ Description
A LocalServer represents a set of entries in the WebCacheDB and allows the set to be managed as a group. The identifying properties of a 
LocalServer are its domain, name, required_cookie, and server_type.
The webcache system supports two types of local servers: ResourceStores and ManagedResourceStores.
Note: use ResourceStores and ManagedResourceStores instead of this base class.

%T% __Sample Code__
<verbatim>
NPL.load("(gl)script/kids/3DMapSystemApp/localserver/localserver.lua");
</verbatim>

---+++ Member Functions

---++++ !localserver:new

<verbatim> Represents an item in the store
local Item = {
   -- type of EntryInfo
   entry = nil,
   -- type of EntryPayload
   payload = nil,
}
  
local localserver = {
   -- true
   is_initialized_,
   -- type of SecurityOrigin
   security_origin_,
   -- string: server store name
   name_,
   -- string: 
   required_cookie_,
   -- type of WebCacheDB.ServerType
   server_type_ = WebCacheDB.ServerType.RESOURCE_STORE,
   -- service id in database
   server_id_,
   -- boolean
   store_might_exist_ = true,
   -- Represents an item in the store
   Item = Item,
   -- default policy
   Cache_policy = Map3DSystem.localserver.CachePolicy:new("access plus 1 hour"),
}</verbatim>;
commonlib.setfield("Map3DSystem.localserver.localserver", localserver);



__syntax__
<verbatim>function localserver:new(o)</verbatim>


__parameters__

| *o* |  |

---++++ !localserver.CanServeLocally

----------------------------------
 public member and static functions: 
----------------------------------

 Returns if the database has a response for the url at this time


__syntax__
<verbatim>function localserver.CanServeLocally(url)</verbatim>


__parameters__

| *url* |  |

---++++ !localserver:Remove

 Removes the server from the DB, deleting all related rows from
 the Servers, Versions, Entries, and Payloads tables


__syntax__
<verbatim>function localserver:Remove()</verbatim>

---++++ !localserver:StillExistsInDB

 Returns true if our server_id_ still exists in the DB.


__syntax__
<verbatim>function localserver:StillExistsInDB() </verbatim>

---++++ !localserver:GetSecurityOrigin

 Returns the SecurityOrigin that was passed into Init


__syntax__
<verbatim>function localserver:GetSecurityOrigin() </verbatim>

---++++ !localserver:GetName

 Returns the name passed into Init


__syntax__
<verbatim>function localserver:GetName() </verbatim>

---++++ !localserver:GetRequiredCookie

 Returns the required_cookie passed into Init


__syntax__
<verbatim>function localserver:GetRequiredCookie() </verbatim>

---++++ !localserver:IsEnabled

 Returns true if local serving of entries in this LocalServer is enabled


__syntax__
<verbatim>function localserver:IsEnabled()</verbatim>

---++++ !localserver:SetEnabled

 Enable or disable local serving of entries in this LocalServer. Returns
 true if successfully modifies the setting.


__syntax__
<verbatim>function localserver:SetEnabled(enabled)</verbatim>


__parameters__

| *enabled* |  |

---++++ !localserver:GetDataDir

 Create/get the data directory path of this server. 
   * _return_ ____ : the dir is returned. it ends with "/". 


__syntax__
<verbatim>function localserver:GetDataDir()</verbatim>


__parameters__

| *return* | the dir is returned. it ends with "/". |

---++++ !localserver:ExistsInDB

-------------------------------------
 protected functions: 
-------------------------------------
 static function: if the server exists in the DB
   * _return_ __server__ :_id or nil if not found. 


__syntax__
<verbatim>function localserver:ExistsInDB(security_origin,name,required_cookie, serverType) </verbatim>


__parameters__

| *security* |  |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |
| *serverType* |  |
| *return* | _id or nil if not found. |

---++++ !localserver:GetServer

 get server info from database. 
   * _param_ __server__ :  nil or a ServerInfo table. 
   * _return_ ____ : nil or the ServerInfo table is returned. 


__syntax__
<verbatim>function localserver:GetServer(server)</verbatim>


__parameters__

| *server* | nil or a ServerInfo table. |

---++++ !localserver:Clone

 clone from input local_server


__syntax__
<verbatim>function localserver:Clone(local_server) </verbatim>


__parameters__

| *local* |  |
| *server* |  |

---++++ !localserver:FindServer

 Retrieves from the DB the server info for this instance using dentifier domain/name/required_cookie/serverType.
   * _return_ __ServerInfo__ : returned or nil if not found. 


__syntax__
<verbatim>function localserver:FindServer(security_origin,name,required_cookie, serverType) </verbatim>


__parameters__

| *security* |  |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |
| *serverType* |  |
| *return* | returned or nil if not found. |

---++++ !localserver:GetVersion

 Retrieves from the DB the version info for the desired ready state|version string
   * _param_ __arg1__ : desired ready state or version string
   * _return_ __VersionInfo__ : or nil if not found. 


__syntax__
<verbatim>function localserver:GetVersion(arg1) </verbatim>


__parameters__

| *arg1* | desired ready state or version string |

---++++ !localserver:Open

 Initializes an instance given it's server_id. Pre: this instance must
 be uninitialized and the server_id must exist in the DB. Upon return,
 successful and otherwise, the  is_initialized_ data member will be setto false. 
   * _NOTE_ ____ : Derived classes must set to true.


__syntax__
<verbatim>function localserver:Open(server_id)</verbatim>


__parameters__

| *server* |  |
| *id* |  |

---++++ !localserver:CreateOrOpen

 Initializes an instance and inserts a row in the Servers table of
 of DB if one is not already present. Pre: this instance must be
 uninitialized.   Upon return, successful and otherwise, the 
 is_initialized_ data member will be set to false. 
   * _NOTE_ ____ : Derived classes must set to true.


__syntax__
<verbatim>function localserver:CreateOrOpen(security_origin, name, required_cookie) </verbatim>


__parameters__

| *security* |  |
| *origin* |  |
| *name* |  |
| *required* |  |
| *cookie* |  |
%STOPINCLUDE%</verbatim>
<nop>
Topic revision: r1 - 2008-02-29 - LiXizhi
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback