From ca724636d4615c6c58d3830fa8ccd620250886ea Mon Sep 17 00:00:00 2001 From: Jeff Ames Date: Thu, 26 Jun 2008 12:38:03 +0000 Subject: [PATCH] Apply patch from bug #1601 -- more documentation for Data/MySQL. Thanks kerunix_Flan! --- OpenSim/Data/MySQL/MySQLAssetData.cs | 61 ++++-- OpenSim/Data/MySQL/MySQLDataStore.cs | 259 +++++++++++++++++++---- OpenSim/Data/MySQL/MySQLGridData.cs | 16 +- OpenSim/Data/MySQL/MySQLInventoryData.cs | 57 +++-- 4 files changed, 315 insertions(+), 78 deletions(-) diff --git a/OpenSim/Data/MySQL/MySQLAssetData.cs b/OpenSim/Data/MySQL/MySQLAssetData.cs index a29e11b3e1..a64a2568a0 100644 --- a/OpenSim/Data/MySQL/MySQLAssetData.cs +++ b/OpenSim/Data/MySQL/MySQLAssetData.cs @@ -36,6 +36,9 @@ using OpenSim.Framework; namespace OpenSim.Data.MySQL { + /// + /// A MySQL Interface for the Asset Server + /// internal class MySQLAssetData : AssetDataBase, IPlugin { private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType); @@ -45,12 +48,16 @@ namespace OpenSim.Data.MySQL #region IPlugin Members /// - /// Initialises Asset interface - /// Loads and initialises the MySQL storage plugin - /// Warns and uses the obsolete mysql_connection.ini if connect string is empty. - /// Check for migration + /// Initialises Asset interface + /// + /// + /// Loads and initialises the MySQL storage plugin. + /// Warns and uses the obsolete mysql_connection.ini if connect string is empty. + /// Check for migration + /// + /// /// - /// connect string. + /// connect string override public void Initialise(string connect) { // TODO: This will let you pass in the connect string in @@ -78,10 +85,16 @@ namespace OpenSim.Data.MySQL } /// - /// uses the obsolete mysql_connection.ini + /// Initialises Asset interface + /// + /// + /// Loads and initialises the MySQL storage plugin + /// uses the obsolete mysql_connection.ini + /// + /// /// - /// connect string. - /// Probably deprecated and shouldn't be used + /// connect string + /// Probably DEPRECATED and shouldn't be used override public void Initialise() { IniFile GridDataMySqlFile = new IniFile("mysql_connection.ini"); @@ -98,6 +111,13 @@ namespace OpenSim.Data.MySQL #region IAssetProvider Members + /// + /// + /// Execute CreateAssetsTable.sql if oldVersion == null + /// do nothing if oldVersion != null + /// + /// + /// private void UpgradeAssetsTable(string oldVersion) { // null as the version, indicates that the table didn't exist @@ -112,6 +132,7 @@ namespace OpenSim.Data.MySQL /// /// Ensure that the assets related tables exists and are at the latest version /// + /// private void TestTables(Migration m) { Dictionary tableList = new Dictionary(); @@ -129,10 +150,11 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Fetch Asset from database /// - /// - /// + /// Asset UUID to fetch + /// Return the asset + /// On failure : throw an exception and attempt to reconnect to database override public AssetBase FetchAsset(LLUUID assetID) { AssetBase asset = null; @@ -175,9 +197,10 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Create an asset in database, or update it if existing. /// - /// + /// Asset UUID to create + /// On failure : Throw an exception and attempt to reconnect to database override public void CreateAsset(AssetBase asset) { lock (_dbConnection) @@ -224,19 +247,19 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Update a asset in database, see /// - /// + /// Asset UUID to update override public void UpdateAsset(AssetBase asset) { CreateAsset(asset); } /// - /// + /// check if the asset UUID exist in database /// - /// - /// + /// The asset UUID + /// true if exist. override public bool ExistsAsset(LLUUID uuid) { bool assetExists = false; @@ -285,7 +308,7 @@ namespace OpenSim.Data.MySQL #endregion /// - /// database provider version + /// Database provider version /// override public string Version { diff --git a/OpenSim/Data/MySQL/MySQLDataStore.cs b/OpenSim/Data/MySQL/MySQLDataStore.cs index 2b4702bf72..aa4c1117d4 100644 --- a/OpenSim/Data/MySQL/MySQLDataStore.cs +++ b/OpenSim/Data/MySQL/MySQLDataStore.cs @@ -40,6 +40,9 @@ using OpenSim.Region.Environment.Scenes; namespace OpenSim.Data.MySQL { + /// + /// A MySQL Interface for the Region Server + /// public class MySQLDataStore : IRegionDataStore { private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType); @@ -76,7 +79,7 @@ namespace OpenSim.Data.MySQL private DataTable m_landAccessListTable; private DataTable m_regionBanListTable; - // Temporary attribute while this is experimental + /// Temporary attribute while this is experimental private bool persistPrimInventories; /*********************************************************************** @@ -177,7 +180,8 @@ namespace OpenSim.Data.MySQL /// /// Given a list of tables, return the version of the tables, as seen in the database /// - /// + /// The list of table + /// The database connection handler public void GetTableVersion(Dictionary tableList, MySqlConnection dbcon) { lock (dbcon) @@ -226,6 +230,7 @@ namespace OpenSim.Data.MySQL /// Execute a SQL statement stored in a resource, as a string /// /// the ressource name + /// The database connection handler public void ExecuteResourceSql(string name, MySqlConnection dbcon) { MySqlCommand cmd = new MySqlCommand(getResourceString(name), dbcon); @@ -260,9 +265,13 @@ namespace OpenSim.Data.MySQL } /// + /// + /// Execute CreateLandTable.sql if oldVersion == null + /// Execute UpgradeLandTable.sqm if oldVersion contain "Rev." + /// /// /// - /// + /// The database connection handler private void UpgradeLandTable(string oldVersion, MySqlConnection dbconn) { // null as the version, indicates that the table didn't exist @@ -280,8 +289,8 @@ namespace OpenSim.Data.MySQL /// /// Adds an object into region storage /// - /// - /// + /// The object + /// The region UUID public void StoreObject(SceneObjectGroup obj, LLUUID regionUUID) { lock (m_dataSet) @@ -307,8 +316,8 @@ namespace OpenSim.Data.MySQL /// /// removes an object from region storage /// - /// - /// + /// The object + /// The Region UUID public void RemoveObject(LLUUID obj, LLUUID regionUUID) { m_log.InfoFormat("[REGION DB]: Removing obj: {0} from region: {1}", obj.UUID, regionUUID); @@ -362,6 +371,7 @@ namespace OpenSim.Data.MySQL /// Load persisted objects from region storage. /// /// the Region UUID + /// List of loaded groups public List LoadObjects(LLUUID regionUUID) { Dictionary createdObjects = new Dictionary(); @@ -448,7 +458,7 @@ namespace OpenSim.Data.MySQL /// /// Load in a prim's persisted inventory. /// - /// + /// The prim private void LoadItems(SceneObjectPart prim) { lock (m_dataSet) @@ -484,7 +494,7 @@ namespace OpenSim.Data.MySQL /// /// Store a terrain revision in region storage /// - /// terrain data + /// HeightField data /// region UUID public void StoreTerrain(double[,] ter, LLUUID regionID) { @@ -513,7 +523,7 @@ namespace OpenSim.Data.MySQL /// Load the latest terrain revision from region storage /// /// the region UUID - /// + /// Heightfield data public double[,] LoadTerrain(LLUUID regionID) { double[,] terret = new double[256,256]; @@ -563,8 +573,10 @@ namespace OpenSim.Data.MySQL } /// - /// delete from land where UUID=globalID - /// delete from landaccesslist where LandUUID=globalID + /// + /// delete from land where UUID=globalID + /// delete from landaccesslist where LandUUID=globalID + /// /// /// public void RemoveLandObject(LLUUID globalID) @@ -629,10 +641,10 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Load (fetch?) a region banlist /// - /// - /// + /// The region UUID + /// The Region banlist public List LoadRegionBanList(LLUUID regionUUID) { List regionbanlist = new List(); @@ -660,9 +672,9 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Add an item to region banlist /// - /// + /// The item public void AddToRegionBanlist(RegionBanListItem item) { lock (m_dataSet) @@ -684,9 +696,9 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Remove an item from region banlist /// - /// + /// The item public void RemoveFromRegionBanlist(RegionBanListItem item) { lock (m_dataSet) @@ -783,7 +795,7 @@ namespace OpenSim.Data.MySQL } /// - /// + /// See /// public void Shutdown() { @@ -798,6 +810,13 @@ namespace OpenSim.Data.MySQL * **********************************************************************/ + /// + /// + /// + /// + /// + /// + /// private static DataColumn createCol(DataTable dt, string name, Type type) { DataColumn col = new DataColumn(name, type); @@ -805,6 +824,10 @@ namespace OpenSim.Data.MySQL return col; } + /// + /// Create the "terrain" table + /// + /// private static DataTable createTerrainTable() { DataTable terrain = new DataTable("terrain"); @@ -815,6 +838,10 @@ namespace OpenSim.Data.MySQL return terrain; } + /// + /// Create the "regionban" table + /// + /// private static DataTable createRegionBanTable() { DataTable regionban = new DataTable("regionban"); @@ -826,6 +853,10 @@ namespace OpenSim.Data.MySQL } + /// + /// Create the "prims" table + /// + /// private static DataTable createPrimTable() { DataTable prims = new DataTable("prims"); @@ -890,6 +921,10 @@ namespace OpenSim.Data.MySQL return prims; } + /// + /// Create the "land" table + /// + /// private static DataTable createLandTable() { DataTable land = new DataTable("land"); @@ -934,6 +969,10 @@ namespace OpenSim.Data.MySQL return land; } + /// + /// Create the "landaccesslist" table + /// + /// private static DataTable createLandAccessListTable() { DataTable landaccess = new DataTable("landaccesslist"); @@ -944,6 +983,10 @@ namespace OpenSim.Data.MySQL return landaccess; } + /// + /// Create the "primshapes" table + /// + /// private static DataTable createShapeTable() { DataTable shapes = new DataTable("primshapes"); @@ -984,6 +1027,10 @@ namespace OpenSim.Data.MySQL return shapes; } + /// + /// Create the "primitems" table + /// + /// private static DataTable createItemsTable() { DataTable items = new DataTable("primitems"); @@ -1025,6 +1072,11 @@ namespace OpenSim.Data.MySQL * **********************************************************************/ + /// + /// + /// + /// + /// private SceneObjectPart buildPrim(DataRow row) { SceneObjectPart prim = new SceneObjectPart(); @@ -1153,6 +1205,11 @@ namespace OpenSim.Data.MySQL return taskItem; } + /// + /// + /// + /// + /// private static LandData buildLandData(DataRow row) { LandData newData = new LandData(); @@ -1214,6 +1271,11 @@ namespace OpenSim.Data.MySQL return newData; } + /// + /// + /// + /// + /// private static ParcelManager.ParcelAccessEntry buildLandAccessData(DataRow row) { ParcelManager.ParcelAccessEntry entry = new ParcelManager.ParcelAccessEntry(); @@ -1223,6 +1285,11 @@ namespace OpenSim.Data.MySQL return entry; } + /// + /// + /// + /// + /// private static Array serializeTerrain(double[,] val) { MemoryStream str = new MemoryStream(65536*sizeof (double)); @@ -1242,6 +1309,13 @@ namespace OpenSim.Data.MySQL return str.ToArray(); } + /// + /// + /// + /// + /// + /// + /// private void fillPrimRow(DataRow row, SceneObjectPart prim, LLUUID sceneGroupID, LLUUID regionUUID) { row["UUID"] = Util.ToRawUuidString(prim.UUID); @@ -1318,6 +1392,11 @@ namespace OpenSim.Data.MySQL } } + /// + /// + /// + /// + /// private static void fillItemRow(DataRow row, TaskInventoryItem taskItem) { row["itemID"] = taskItem.ItemID; @@ -1343,6 +1422,12 @@ namespace OpenSim.Data.MySQL row["flags"] = taskItem.Flags; } + /// + /// + /// + /// + /// + /// private static void fillLandRow(DataRow row, LandData land, LLUUID regionUUID) { row["UUID"] = Util.ToRawUuidString(land.globalID); @@ -1382,6 +1467,12 @@ namespace OpenSim.Data.MySQL row["AuthBuyerID"] = land.authBuyerID; } + /// + /// + /// + /// + /// + /// private static void fillLandAccessRow(DataRow row, ParcelManager.ParcelAccessEntry entry, LLUUID parcelID) { row["LandUUID"] = Util.ToRawUuidString(parcelID); @@ -1389,6 +1480,11 @@ namespace OpenSim.Data.MySQL row["Flags"] = entry.Flags; } + /// + /// + /// + /// + /// private PrimitiveBaseShape buildShape(DataRow row) { PrimitiveBaseShape s = new PrimitiveBaseShape(); @@ -1447,6 +1543,11 @@ namespace OpenSim.Data.MySQL return s; } + /// + /// + /// + /// + /// private void fillShapeRow(DataRow row, SceneObjectPart prim) { PrimitiveBaseShape s = prim.Shape; @@ -1502,6 +1603,12 @@ namespace OpenSim.Data.MySQL } } + /// + /// + /// + /// + /// + /// private void addPrim(SceneObjectPart prim, LLUUID sceneGroupID, LLUUID regionUUID) { lock (m_dataSet) @@ -1535,7 +1642,11 @@ namespace OpenSim.Data.MySQL } } - // see IRegionDatastore + /// + /// see IRegionDatastore + /// + /// + /// public void StorePrimInventory(LLUUID primID, ICollection items) { if (!persistPrimInventories) @@ -1576,17 +1687,24 @@ namespace OpenSim.Data.MySQL * **********************************************************************/ + /// + /// Create a MySQL insert command + /// + /// + /// + /// + /// + /// This is subtle enough to deserve some commentary. + /// Instead of doing *lots* and *lots of hardcoded strings + /// for database definitions we'll use the fact that + /// realistically all insert statements look like "insert + /// into A(b, c) values(:b, :c) on the parameterized query + /// front. If we just have a list of b, c, etc... we can + /// generate these strings instead of typing them out. + /// private static MySqlCommand createInsertCommand(string table, DataTable dt) { - /** - * This is subtle enough to deserve some commentary. - * Instead of doing *lots* and *lots of hardcoded strings - * for database definitions we'll use the fact that - * realistically all insert statements look like "insert - * into A(b, c) values(:b, :c) on the parameterized query - * front. If we just have a list of b, c, etc... we can - * generate these strings instead of typing them out. - */ + string[] cols = new string[dt.Columns.Count]; for (int i = 0; i < dt.Columns.Count; i++) { @@ -1611,6 +1729,13 @@ namespace OpenSim.Data.MySQL return cmd; } + /// + /// Create a MySQL update command + /// + /// + /// + /// + /// private static MySqlCommand createUpdateCommand(string table, string pk, DataTable dt) { string sql = "update " + table + " set "; @@ -1638,6 +1763,11 @@ namespace OpenSim.Data.MySQL return cmd; } + /// + /// + /// + /// + /// private static string defineTable(DataTable dt) { string sql = "create table " + dt.TableName + "("; @@ -1673,16 +1803,18 @@ namespace OpenSim.Data.MySQL **********************************************************************/ /// - /// This is a convenience function that collapses 5 repetitive + /// This is a convenience function that collapses 5 repetitive /// lines for defining MySqlParameters to 2 parameters: /// column name and database type. - /// + /// + /// /// It assumes certain conventions like ?param as the param /// name to replace in parametrized queries, and that source /// version is always current version, both of which are fine /// for us. - /// - ///a built MySql parameter + /// + /// + /// a built MySql parameter private static MySqlParameter createMySqlParameter(string name, Type type) { MySqlParameter param = new MySqlParameter(); @@ -1693,6 +1825,11 @@ namespace OpenSim.Data.MySQL return param; } + /// + /// + /// + /// + /// private void SetupPrimCommands(MySqlDataAdapter da, MySqlConnection conn) { MySqlCommand insertCommand = createInsertCommand("prims", m_primTable); @@ -1709,6 +1846,11 @@ namespace OpenSim.Data.MySQL da.DeleteCommand = delete; } + /// + /// + /// + /// + /// private void SetupItemsCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("primitems", m_itemsTable); @@ -1722,6 +1864,12 @@ namespace OpenSim.Data.MySQL delete.Connection = conn; da.DeleteCommand = delete; } + + /// + /// + /// + /// + /// private void SetupRegionBanCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("regionban", m_regionBanListTable); @@ -1736,12 +1884,23 @@ namespace OpenSim.Data.MySQL delete.Connection = conn; da.DeleteCommand = delete; } + + /// + /// + /// + /// + /// private void SetupTerrainCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("terrain", m_dataSet.Tables["terrain"]); da.InsertCommand.Connection = conn; } + /// + /// + /// + /// + /// private void setupLandCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("land", m_dataSet.Tables["land"]); @@ -1751,12 +1910,22 @@ namespace OpenSim.Data.MySQL da.UpdateCommand.Connection = conn; } + /// + /// + /// + /// + /// private void setupLandAccessCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("landaccesslist", m_dataSet.Tables["landaccesslist"]); da.InsertCommand.Connection = conn; } + /// + /// + /// + /// + /// private void SetupShapeCommands(MySqlDataAdapter da, MySqlConnection conn) { da.InsertCommand = createInsertCommand("primshapes", m_dataSet.Tables["primshapes"]); @@ -1771,6 +1940,10 @@ namespace OpenSim.Data.MySQL da.DeleteCommand = delete; } + /// + /// + /// + /// MySQL connection handler private static void InitDB(MySqlConnection conn) { string createPrims = defineTable(createPrimTable()); @@ -1859,6 +2032,12 @@ namespace OpenSim.Data.MySQL conn.Close(); } + /// + /// + /// + /// + /// + /// private bool TestTables(MySqlConnection conn, Migration m) { // we already have migrations, get out of here @@ -1968,6 +2147,11 @@ namespace OpenSim.Data.MySQL * **********************************************************************/ + /// + /// Type conversion functions + /// + /// + /// private static DbType dbtypeFromType(Type type) { if (type == typeof (String)) @@ -2000,8 +2184,11 @@ namespace OpenSim.Data.MySQL } } - // this is something we'll need to implement for each db - // slightly differently. + /// + /// + /// + /// + /// this is something we'll need to implement for each db slightly differently. private static string MySqlType(Type type) { if (type == typeof (String)) diff --git a/OpenSim/Data/MySQL/MySQLGridData.cs b/OpenSim/Data/MySQL/MySQLGridData.cs index 394dbbdc87..7abc85a391 100644 --- a/OpenSim/Data/MySQL/MySQLGridData.cs +++ b/OpenSim/Data/MySQL/MySQLGridData.cs @@ -49,10 +49,14 @@ namespace OpenSim.Data.MySQL private MySQLManager database; /// - /// Initialises Grid interface - /// Loads and initialises the MySQL storage plugin - /// Warns and uses the obsolete mysql_connection.ini if connect string is empty. - /// Check for migration + /// Initialises Grid interface + /// + /// + /// Loads and initialises the MySQL storage plugin + /// Warns and uses the obsolete mysql_connection.ini if connect string is empty. + /// Check for migration + /// + /// /// /// connect string. override public void Initialise(string connect) @@ -410,8 +414,8 @@ namespace OpenSim.Data.MySQL /// /// Adds a location reservation /// - /// - /// + /// x coordinate + /// y coordinate /// override public ReservationData GetReservationAtPoint(uint x, uint y) { diff --git a/OpenSim/Data/MySQL/MySQLInventoryData.cs b/OpenSim/Data/MySQL/MySQLInventoryData.cs index 2d93df33b6..911958c48c 100644 --- a/OpenSim/Data/MySQL/MySQLInventoryData.cs +++ b/OpenSim/Data/MySQL/MySQLInventoryData.cs @@ -49,12 +49,16 @@ namespace OpenSim.Data.MySQL private MySQLManager database; /// - /// Initialises User interface - /// Loads and initialises the MySQL storage plugin - /// warns and uses the obsolete mysql_connection.ini if connect string is empty. - /// Check for migration + /// Initialises Inventory interface + /// + /// + /// Loads and initialises the MySQL storage plugin + /// warns and uses the obsolete mysql_connection.ini if connect string is empty. + /// Check for migration + /// + /// /// - /// connect string. + /// connect string public void Initialise(string connect) { if (connect != String.Empty) @@ -90,6 +94,13 @@ namespace OpenSim.Data.MySQL #region Test and initialization code + /// + /// + /// Execute CreateFoldersTable.sql if oldVersion == null + /// do nothing if oldVersion != null + /// + /// + /// private void UpgradeFoldersTable(string oldVersion) { // null as the version, indicates that the table didn't exist @@ -99,13 +110,19 @@ namespace OpenSim.Data.MySQL return; } - // if the table is already at the current version, then we can exit immediately -// if (oldVersion == "Rev. 2") -// return; - -// database.ExecuteResourceSql("UpgradeFoldersTableToVersion2.sql"); + //// if the table is already at the current version, then we can exit immediately + // if (oldVersion == "Rev. 2") + // return; + // database.ExecuteResourceSql("UpgradeFoldersTableToVersion2.sql"); } + /// + /// + /// Execute CreateItemsTable.sql if oldVersion == null + /// Execute "UpgradeItemsTableToVersion3.sql" if oldVersion start with "Rev. 2;" + /// + /// + /// private void UpgradeItemsTable(string oldVersion) { // null as the version, indicates that the table didn't exist @@ -123,6 +140,11 @@ namespace OpenSim.Data.MySQL } } + /// + /// + /// + /// MySQL connection handler + /// private void TestTables(MySqlConnection conn, Migration m) { Dictionary tableList = new Dictionary(); @@ -178,7 +200,7 @@ namespace OpenSim.Data.MySQL /// /// Returns the version of this DB provider /// - /// A string containing the DB provider + /// A string containing the DB provider version public string getVersion() { return database.getVersion(); @@ -260,9 +282,9 @@ namespace OpenSim.Data.MySQL /// - /// see InventoryItemBase.getUserRootFolder + /// see /// - /// + /// The user UUID /// public InventoryFolderBase getUserRootFolder(LLUUID user) { @@ -545,9 +567,9 @@ namespace OpenSim.Data.MySQL } /// - /// + /// Detele the specified inventory item /// - /// + /// The inventory item UUID to delete public void deleteInventoryItem(LLUUID itemID) { try @@ -609,9 +631,10 @@ namespace OpenSim.Data.MySQL } /// - /// Creates a new inventory folder + /// Move an inventory folder /// - /// Folder to create + /// Folder to move + /// UPDATE inventoryfolders SET parentFolderID=?parentFolderID WHERE folderID=?folderID public void moveInventoryFolder(InventoryFolderBase folder) { string sql =