JSORM.db.channel
From Jsorm
Contents |
Overview
A channel is responsible for sending information to and receiving information from a remote source, and is used directly only by jsormdb to communicate with the remote data source. The remote source could be anything at all. For example:
- An http server
- A non-http server
- Another jsormdb
- An ExtJS data store
- A text file
- Anything at all
A channel shipped with jsormdb will normally be in the object JSORM.db.channel.
Limitations
The ability of a channel to actually communicate with a remote data source may be significantly constrained by the operating environment. For example, a browser will normally only allow a network communication to the server from which the JavaScript itself was received, and will normally not allow any local disk access at all. On the other hand, a Rhino JavaScript environment program or Mozilla plugin will have much broader access.
Signature
A channel is not required to have configuration parameters, but may choose to. These configuration parameters are normally used to set up access to the remote data source. For specific configuration of the http channel that ships with jsormdb, see JSORM.db.channel.http.
A channel is expected to have the following methods defined:
- update: Called when the channel is expected to send data to the remote data source.
- load: Called when the channel is expected to retrieve data from the remote data source.
Update
Update accepts a single object as an argument. The object has the following properties:
- params: Parameters to pass to the remote data source.
- callback: Function to call when the update is complete. The callback expects a single argument, a JavaScript object. The object has the following properties:
- options: options object passed through to the original update call
- success: boolean if the update succeeded or failed
- data: the response, if any, from the remote data source, often used to update the local store
- scope: Scope within which to execute the callback.
- options: Options object to pass as argument to the callback.
Load
Load accepts a single object as an argument. The object has the following properties:
- params: Parameters to pass to the remote data source.
- callback: Function to call when the load is complete. The callback expects a single argument, a JavaScript object. The object has the following properties:
- options: options object passed through to the original load call
- success: boolean if the load succeeded or failed
- data: the data from the remote data source to use to load the store
- scope: Scope within which to execute the callback.
- options: Options object to pass as argument to the callback.
Events
The channel is expected to fire the following events:
- beforeload: Before attempting a load. If any handler returns false, do not complete the load.
- load: After load is successful.
- loadexception: After a load has failed.
- beforeupdate: Before attempting an update. If any handler returns false, do not complete the update.
- update: After update is successful.
- updateexception: After an update has failed.
