Databázová vrstva hry Space Traffic, tým MLAB

Databázová vrstva hry Space Traffic, tým MLAB

Databázová vrstva hry Space Traffic, tým MLAB
Návod na používání perzistentní vrstvy
Vytvořeno dne 4. 5. 2012, autor: Jan Rabušic
1. Jak užívat perzistentní vrstvu
Perzistentní vrstva nabízí metody, které poskytují CRUD (create, read, update, delete) operace nad
persistentním úložištěm (databází). Jak je možné tyto metody vyvolat bude popsáno v kapitole Popis
užití a názorně předvedeno na ukázkovém příkladu v kapitole Příklad užití.
1.1 Popis užití
Perzistentní vrstva je tvořena Data Access Objects (dále jen DAO), ke kterým je přistupováno pomocí
PersistenceManager. PersistenceManager se nachází ve jmenném prostoru SpaceTraffic.Engine. DAO
objekty jsou poskytovány jmenným prostorem SpaceTraffic.Dao, ale není zvykem přistupovat k nim
jinak, než pomocí PersistenceManager, tedy jmenný prostor SpaceTraffic.Dao není pro využití
persistentní vrstvy nutný.
Parametry metod DAO objektů, respektive jejich návratové hodnoty jsou objekty ze jmenného
prostoru SpaceTraffic.Entities (Player, SpaceShip, Base, Factory, Cargo, SpaceShipCargo a Message),
jejich seznamy (List<Player>, atd.), int, string, nebo bool.
Pro zavolání konkrétní metody perzistentní vrstvy musíte mít nejprve instanci objektu
PersistenceManager. Jeho metodami Get[název požadované entity]DAO získáte instanci
požadovaného DAO, jehož CRUD metody můžete pak využívat.
1.2 Příklad užití
Mnohem výstižnější, než slovní popis, jsou ukázky, jak lze perzistentní vrstvu využít.
Ukázka č. 1 – získání seznamů všech lodí:
1
2
PersistenceManager pm = new PersistenceManager();
List<SpaceShip> spaceShips = pm.GetSpaceShipDAO().GetSpaceShips();
Ukázka č. 2 – získání seznamů všech lodí s uchováním si instance DAO (vyžaduje SpaceTraffic.Dao):
1
2
3
PersistenceManager pm = new PersistenceManager();
ISpaceShipDAO spaceShipDAO = pm.GetSpaceShipDAO();
List<SpaceShip> spaceShips = spaceShipDAO.GetSpaceShips();
Ukázka č. 3 – vložení lodi do DB:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
PersistenceManager pm = new PersistenceManager();
SpaceShip ship = new SpaceShip();
ship.CurrentStarSystem = "Země";
ship.SpaceShipName = "Moje lod";
ship.SpaceShipModel = "model";
ship.DamagePercent = 40;
ship.FuelTank = 50;
ship.CurrentFuelTank = 34;
ship.UserCode = "Go to ...";
ship.TimeOfArrival = "12:00";
ship.PlayerId = player.PlayerId;
ship.IsFlying = true;
ship.DockedAtBaseId = newBase.BaseId;
if (pm.GetSpaceShipDAO().InsertSpaceShip(ship))
{
16
17
18
19
20
21
}
else
{
};
Console.Out.WriteLine("Vlozeni probehlo uspesne.");
Console.Out.WriteLine("Vlozeni neuspesne.");
Ukázka č. 4 – smazání lodi z DB:
1
2
3
4
5
6
7
8
9
PersistenceManager pm = new PersistenceManager();
if (pm.GetSpaceShipDAO().RemoveSpaceShipById(id))
{
Console.Out.WriteLine("Smazani probehlo uspesne.");
}
else
{
Console.Out.WriteLine("Smazani neuspesne.");
}
Ukázka č. 5 – změna údajů o lodi:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
PersistenceManager pm = new PersistenceManager();
ISpaceShipDAO spaceShipDAO = pm.GetSpaceShipDAO();
SpaceShip ship = spaceShipDAO.GetSpaceShipById(id);
if (ship != null)
{
ship.IsFlying = false;
if (spaceShipDAO.UpdateSpaceShipById(ship))
{
Console.Out.WriteLine("Update probehl uspesne.");
}
else
{
Console.Out.WriteLine("Update neprobehl uspesne.");
}
}
else
{
Console.Out.WriteLine("Dana lod nenalezena.");
};
2. Seznam dostupných metod
2.1 PersistenceManager
void Initialize()
Inicializuje databázi.
void TestDbConnection()
Testuje dostupnost připojení k databázi.
IPlayerDAO GetPlayerDAO()
Vytváří a vrací instanci DAO hráče.
IMessageDAO GetMessageDAO()
Vytváří a vrací instanci DAO zprávy.
ICargoDAO GetCargoDAO()
Vytváří a vrací instanci DAO nákladu.
IFactoryDAO GetFactoryDAO()
Vytváří a vrací instanci DAO továrny.
ISpaceShipDAO GetSpaceShipDAO()
Vytváří a vrací instanci DAO vesmírné lodi.
ISpaceShipCargoDAO GetSpaceShipCargoDAO()
Vytváří a vrací instanci DAO nákladu vesmírné lodi.
IBaseDAO GetBaseDAO()
Vytváří a vrací instanci DAO základny.
2.2 PlayerDAO
List<Player> GetPlayers()
Vrací z DB seznam všech hráčů.
Player GetPlayerById(int playerId)
Vrací z DB hráče podle jeho ID.
Player GetPlayerByName(string playerName)
Vrací z DB hráče podle jeho jména.
Player GetPlayerByEmail(string email)
Vrací z DB hráče podle jeho emailu.
bool InsertPlayer(Player player)
Vkládá hráče do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemovePlayerById(int playerId)
Odstraňuje hráče z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool UpdatePlayerById(Player player)
Mění hráče v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
2.3 MessageDAO
Message GetMessage(int messageId)
Vrací z DB zprávu podle její ID.
List<Message> GetMessagesToPlayer(int playerToId)
Vrací z DB seznam zpráv směřovaných konkrétnímu uživateli.
List<Message> GetMessagesFrom(string name)
Vrací z DB seznam zpráv od konkrétního zdroje.
bool InsertMessage(Message message)
Vkládá zprávu do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveMessage(int messageId)
Odstraňuje zprávu z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
2.4 CargoDAO
List<Cargo> GetCargos()
Vrací z DB seznam všech nákladů.
Cargo GetCargoById(int CargoId)
Vrací z DB náklad podle jeho ID.
List<Cargo> GetCargosByType(string type)
Vrací z DB seznam všech nákladů odpovídajícího typu.
bool InsertCargo(Cargo Cargo)
Vkládá náklad do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveCargoById(int CargoId)
Odstraňuje náklad z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool UpdateCargoById(Cargo Cargo)
Mění náklad v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
2.5 FactoryDAO
List<Factory> GetFactories()
Vrací z DB seznam všech základen.
Factory GetFactoryById(int factoryId)
Vrací z DB základnu podle její ID.
List<Factory> GetFactoriesByPlanet(string planet)
Vrací z DB seznam základen na dané planetě.
List<Factory> GetFactoriesByType(string type)
Vrací z DB seznam základen daného typu.
bool InsertFactory(Factory factory)
Vkládá základnu do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveFactoryById(int factoryId)
Odstraňuje základnu z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool UpdateFactoryById(Factory factory)
Mění základnu v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
2.6 SpaceShipDAO
List<SpaceShip> GetSpaceShips()
Vrací z DB seznam všech vesmírných lodí.
List<SpaceShip> GetSpaceShipsByPlayer(int playerId)
Vrací z DB seznam vesmírných lodí daného hráče.
SpaceShip GetSpaceShipById(int spaceShipId)
Vrací z DB vesmírnou loď podle její ID.
bool InsertSpaceShip(SpaceShip spaceShip)
Vkládá vesmírnou loď do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveSpaceShipById(int spaceShipId)
Odstraňuje vesmírnou loď z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool UpdateSpaceShipById(SpaceShip spaceShip)
Mění vesmírnou loď v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
2.7 SpaceShipCargoDAO
bool InsertSpaceShipCargo(SpaceShipCargo spaceShipCargo)
Vkládá náklad vesmírné lodi do DB. Návratová hodnota true značí úspěch operace, false značí
neúspěch.
bool UpdateCargoCountById(SpaceShipCargo spaceShipCargo)
Mění náklad vesmírné lodi v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveSpaceShipCargoById(int spaceShipId, int cargoId)
Odstraňuje náklad vesmírné lodi z DB. Návratová hodnota true značí úspěch operace, false značí
neúspěch.
List<SpaceShipCargo> GetSpaceShipCargoBySpaceShipId(int spaceShipId)
Vrací z DB seznam nákladů vesmírné lodi.
2.8 BaseDAO
List<Base> GetBases()
Vrací z DB seznam všech základen.
Base GetBaseById(int baseId)
Vrací z DB základnu podle její ID.
bool InsertBase(Base bbase)
Vkládá základnu do DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool RemoveBaseById(int baseId)
Odstraňuje základnu z DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
bool UpdateBaseById(Base bbase)
Mění základnu v DB. Návratová hodnota true značí úspěch operace, false značí neúspěch.
3. Nastavení připojení do databáze
Perzistentní vrstva pracuje s MS SQL databází. Připojení k ní je uloženo v XML souboru
ConnectionStrings.config.default v projektu GameServer. Během vývoje hry SpaceTraffic je
defaultně nastavena perzistentní vrstva tak, aby používala lokální server každého vývojáře.
Ačkoliv je tento lokální SQL Server součástí instalace MS Visual Studia, ne každému se daří spojit se
svým lokálním serverem tímto defaultním nastavením. Pokud nefunguje, je potřeba provést tyto
kroky:
Zjistit hostname počítače a název serveru:
1.
2.
3.
4.
5.
6.
Spusťte SQL Configuration Manager
Vlevo vyberte volbu SQL Server Services
V pravé části okna vyberte běžící server, na kterém chcete mít databázi. 1
Zvolte Vlastnosti (v kontextové nabídce konkrétního serveru)
Vyberte záložku Service.
Zde si opište položku Host name (například USER-PC) a údaj uvedený v závorce u položky
Name (například SQLEXPRESS)
Změnit connection string:
1.
2.
3.
4.
1
V MS Visual Studio otevřete SpaceTraffic solution
Vyberte projekt GameServer a v něm otevřete coubor ConnectionStrings.config.default
V connectionStrings vyberte element add, jehož název (atribut name) je SpaceTrafficContext
Hodnotu atributu connectionString upravte tak, že Data Source=(local); přepíšete na Data
Source=host name\název serveru; (podle našeho příkladu by konkrétní znění bylo Data
Source=USER-PC\SQLEXPRESS;)
Pokud takový server nemáte, nainstalujte si MS SQL Server 2008 Express (dostupný z MSDNAA) podle návodu na instalaci
SQL Serveru.