OpenSim.Region.DataSnapshot
From OpenSimulator
 |
Languages: |
|
The DataSnapshot module is an IRegionModule that takes data from various parts of the OpenSimulator Scene and spits out a custom-format XML file. From this you can have web services mashup with the output data. Consider it analogous to a "Search API", although it's not limited to simple Search. It was birthed after a discussion on the mailing list several months ago about search when Diva contacted me and gave me her ideas. Throughout the course of about a month off and on we worked on this proof-of-concept module. I'm calling it a proof-of-concept for now.
The only data that is being exposed at this point is region info and parcel data for parcels marked "Show in search".
Module inner workings
The module is implemented as any other Region Module. The IRegionModule class itself is DataSnapshotManager.
DataSnapshotManager
This is the 'main' class for the module - it handles registering the IDataSnapshotProvider objects, creates the DataRequestHandler, and contains functions for generating snapshots. Notable functions:
- Initialise - Obtained from IRegionModule. Checks if the config is loaded, and adds each scene being simulated to it's internal list of regions to scrape for data.
- PostInitialise - The second most important function. Registers the timer callback, and searches the containing Assembly for IDataSnapshotProvider objects. Creates an IDataSnapshotProvider for each Scene and IDataSnapshotProvider combination. When the format and interface stabilises, we can then let this start checking other Assemblies for IDataSnapshotProviders. Then it makes the DataRequestHandler object and hands it the first scene. Finally, it checks to see if it needs to ping any external servers (as determined by configuration).
- Snapshot (private) - Spits out an XmlDocument from a Scene. Each XmlDocument can be sent directly as a response to a data request, but GetSnapshot can also merge them into a single response for every Scene being simulated by the host.
- GetSnapshot - Called from DataSnapshotManager. Should really be a part of DataRequestHandler.
- MakeRegionNode - Creates some of the XML in the format, would be in a IDataSnapshotProvider but currently the way their output goes into the format doesn't mesh with the interface well. Might want to rework the format later or something.
- NotifyDataServices - Responsible for pinging an external server defined in our configuration options.
- SnapshotTimerCallback - Notable for being useless. All it does is call MakeNewSnapshot. If you want anything else to happen when the snapshot timer elapses, add it here. I really should have just added MakeNewSnapshot to the timer directly.
- GetErrorMessage - Makes an error for GetSnapshot in case of an exception (missing file, etc)
- GetGridSnapshotData - Takes key-value pairs from GridData and makes it into XML, populated during the first Initialise call.
- GetRegionCategory - Helper function, only notable because originally when the Scene had no Mature or PG flag set it would return "PN Testing Sandbox", aka griefer heaven. Now returns a completely boring "Unknown", hence the comment.
...I think that's everything worth mentioning.
DataRequestHandler
A very small class that makes responses to requests for data.... All it does is register a callback to Scene.AddHTTPHandler - a function we added to Scene just for this module. Yes you can register handlers to BaseHTTPServer from a RegionModule now.
Really deserves to have the GetSnapshot function instead of DataSnapshotManager.
IDataSnapshotProvider
You'll find it in the interfaces folder. This nice little class provides most of the data for our module. The Interface exposed is analogous to IRegionModule, and is loaded in the same way except that we currently only load from the same Assembly.
public interface IDataSnapshotHandler {
XmlNode RequestSnapshotData (XmlDocument document);
void Initialize (Scene scene, DataSnapshotManager parent);
Scene GetParentScene { get; }
}
- Initialize - Gives you a scene and parent object. Also you can establish some callbacks if you want.
- RequestSnapshotData - Gives you an XmlDocument to use as a node factory. Return an XmlNode here, one made from the factory. (Otherwise exceptions will result)
- GetParentScene - Return the parent scene here.
XML Format
Write this later (should be evident from code)
Config options
You need to have a [DataSnapshot] section in your OpenSim.ini configuration and index_sims set to true before DataSnapshot will do anything. Other interesting options:
- snapshot_cache_directory - Folder to save snapshots to. Default is "DataSnapshot".
- data_services - Server(s) to ping to alert of snapshots.
- disable_modules - Option to disable a module by name. Not actually working yet.
Todos
- Script-provided Snapshot data. Would require adding a function to the common builtin commands _OR_ reworking the script engine to allow RegionModules to register their own functions to ScriptEngines. The first one is easy but WRONG, the second one is right but HARD.
- Regression test with 3Di's OpenSim Load Balancing and Region Splitting work. Theoretically, this shouldn't create any problems since we don't make any permenant data that needs to be transferred with a simulator. MAYBE the data services option, since that would probably be the choice of the region owner and should float with the region.
- Make disable_modules work
- Etc
Services that use this data
If your simulator is facing the public internet, and you have enabled the DataSnapshot module, the data that is exposed through it is made available to anyone that asks for it through http://<your IP address>:<port>/?method=collector. Anyone can develop data services based on this public data.
At the moment, there is one 3rd party search service provided by Metaverse Ink that uses this data. To search these opensims, go to http://metaverseink.com. This service, for now, is also just a proof of concept showing how to close the loop between data exposure and data use.
