štvrtok 9. decembra 2010

NHibernate a automaticky udržiavané časové známky (timestamps)


Keď padne rozhodnutie používať vo vašom projekte NHibernate, môžete si v mnohých ohľadoch uľahčiť život (teda hneď potom, čo si omotáte hlavu okolo tejto zázračnej technológie). V tomto blogu vám ukážem ako dohovoriť NHibernate, aby automaticky udržiavalo timestamps na vami-zvolených poliach (teda reálne budete potrebovať mať nanájvyš jedno pole automaticky timestampované).

Ako príklad si uvedieme nasledovné: Užívateľ vašej (webovej) aplikácie uverejní komentár. Tento komentár bude vo vašej aplikácii obsahovať samotný text komentára a časové pole DateUpdated, v ktorom budete chcieť udržiavať dátum a čas zverejnenia/poslednej úpravy komentára. Zakaždým keď užívateľ komentár zverejní, alebo upraví, a obsah komentára je vpísaný/aktualizovaný v databáze, chceme aby sa zaznamenal aj aktuány časový údaj. Toto by za vás mohlo robiť NHibernate, stačí si ho tak nastaviť. Dobre sledujte nasledujúcich pár riadkov kódu, alebo si tie riadky skrátka len skopírujte a použite.

Najprv vás zasypem kódom a potom trošku pokecáme o tom ako to funguje. Budeme potrebovať triedu implementujúcu dve NHibernate interface-y: IPreUpdateEventListener, IPreInsertEventListener. Táto trieda bude potrebovať dva namespace-y, ktoré si môžeme pridať medzi ostatné základné namespace-y ktoré dostaneme pri vytvorení novej čistej triedy:

using NHibernate.Event;
using NHibernate.Persister.Entity;

Trieda samotná bude vyzerať takto:

1 public class TimestampOnInsertUpdate : IPreUpdateEventListener, IPreInsertEventListener
2 {
3  public bool OnPreUpdate(PreUpdateEvent @event)
4  {
5   return !AutoUpdateTimestamps(@event.Entity, @event.Persister, @event.State, true);
6  }
7 
8  public bool OnPreInsert(PreInsertEvent @event)
9  {
10   return !AutoUpdateTimestamps(@event.Entity, @event.Persister, @event.State, false);
11  }
12 
13  private bool AutoUpdateTimestamps(object entity, IEntityPersister persister, object[] state, bool isUpdate)
14  {
15   var dateTimeProperties = entity.GetType().GetProperties().Where(p => p.PropertyType.Equals(typeof(DateTime)));
16   var autoTimestampedProperties = dateTimeProperties.Where(p => p.GetCustomAttributes(false).OfType().Any());
17   if (!autoTimestampedProperties.Any())
18   {
19    return true;
20   }
21   
22   IEnumerable propertiesToTimestamp;
23   if (isUpdate)
24   {
25    propertiesToTimestamp = autoTimestampedProperties.Where(p => !p.GetCustomAttributes(false).OfType().First().InsertOnly);
26   }
27   else
28   {
29    propertiesToTimestamp = autoTimestampedProperties;
30   }
31 
32   if (!autoTimestampedProperties.Any())
18   {
19    return true;
20   }
34 
35   var timestamp = DateTime.Now;
36   try
37   {
38    foreach (var propertyToTimestamp in propertiesToTimestamp)
39    {
40     Set(persister, state, propertyToTimestamp.Name, timestamp);
41     propertyToTimestamp.SetValue(entity, timestamp, null);
42    }
43   }
44   catch (InvalidOperationException)
45   {
46    return false;
47   }
48   return true;
49  }
50 
51  private void Set(IEntityPersister persister, object[] state, string propertyName, object value)
52  {
53   var index = Array.IndexOf(persister.PropertyNames, propertyName);
54   state[index] = value;
55  }
56 }

Ďalej si budeme potrebovať nadefinovať svoju vlastnú atribútu (custom attribute) AutoUpdatedTimestampAttribute, ktorej definícia bude veľmi jednoduchá:

[AttributeUsage(AttributeTargets.Property, AllowMultiple=false)]
public sealed class AutoUpdatedTimestampAttribute : System.Attribute {

 public bool InsertOnly { get; set; }

 public AutoUpdatedTimestampAttribute()
 {
  InsertOnly = false;
 }
}

Naša modelová trieda bude potom môcť takto jednoducho prehlásiť, že niektoré z jej vlastností (properties) potrebujú mať vždy automaticky aktualizovanú časovú známku (timestamp). Príkladná trieda dole napríklad našepkáva NHibernate, žeby bola rada keby sa jej ktosi ujal a aktualizoval jej DateUpdated vlastnosť (pri každom uložení zmeny alebo vytvorení nového záznamu v databáze). Taktiež sa zmieňuje, že by bolo fajn keby pred vložením záznamu (ale len pre vložením) do databázy bola vlastnosť DateCreated nastavená na aktuálny dátum/čas.

...
public virtual string Comments { get; set; }
public virtual DateTime DateLastUsed { get; set; }

[AutoUpdatedTimestamp]
public virtual DateTime DateUpdated { get; set; }

[AutoUpdatedTimestamp(InsertOnly=true)]
public virtual DateTime DateCreated { get; set; }
...

Ešte nám treba objasniť NHibernate, že kde bolo tam bolo, žila raz jedna trieda TimestampOnInsertUpdate, ktorá sa zaujíma o dianie v NHibernate mechanizme pred insert-om/update-om. Stačí pár riadkov medzi nakonfigurovanie NHibernate a vytvorenie ISessionFactory:

var nhConfig = new NHibernate.Cfg.Configuration().Configure();
var timestamper = new TimestampOnInsertUpdate();
nhConfig.EventListeners.PreUpdateEventListeners = new NHibernate.Event.IPreUpdateEventListener[] { timestamper };
nhConfig.EventListeners.PreInsertEventListeners = new NHibernate.Event.IPreInsertEventListener[] { timestamper };
return nhConfig.BuildSessionFactory();

Mohli by sme ich tu zaregistrovať viac než dosť, keďže priradzujeme pole event listernerov. Mohli by sme si zostaviť celú radu listenerov takto:

nhConfig.EventListeners.PreUpdateEventListeners = new NHibernate.Event.IPreUpdateEventListener[] {
 timestamper, id_generator, some_other_listener, nonsense_generator, ...
};
...

Ale to hádam všetci vieme :-)

Ako to funguje


Naša NHibernate IPreInsertEventListener a IPreUpdateEventListener implementujúca trieda je asi najzaujímavejšia časť z toho čo som tu uviedol. Preto som k jej kódu pripojil aj čísla riadkov, aby sa mi na ňu lepšie komentovalo. (Ak vám čísla riadkov prekážajú pri copy-paste robote, vedzte, že nie je prečo robiť paniku: Visual Studio má schopnosť stĺpcovej editácie a tak si pokojne vložte kód aj s číslami do Visual Studia a potom stlačte a držte Alt a myškou označte celý stĺpec čísel a tabulátorov. Zmažeme a práca hotová.)

Najprv však v skratke popíšem všetko ostatné a prečo sme to nakódovali tak ako sme to nakódovali a nie nejak ináč (v článku uvedenom na spodku blogu je uvedený trošku iný príklad používajúci IAuditable interface (ak sa nemýlim)). Využitím vlastnej atribúty a neskôr reflection mechanizmu získame flexibilitu - naše modelové triedy nemusia implementovať žiaden konkrétny interface, ich DateTime vlastnosti nemusia mať také-či-onaké konkrétne predpísané meno, ale je celkom na nás, ktorú vlastnosť označíme našou atribútou. Ak by sme časom odpojili náš IPreInsertEventListener / IPreUpdateEventListener od NHibernate (rozhodli sa nepoužiť NHibernate na udržiavanie časových známok (rozhodneme sa použiť default values na databázových poliach, resp. databázové trigger-y alebo inú metódu), naše modelové triedy môžu pokojne zostať nezmenené, pretože atribúty ani nemusíme odobrať - ak nie sú nikým využité, nevadí.

Náš listener sa dá jednoducho zapojiť / odpojiť z mechanizmu NHibernate, ako sme videli vyššie. Samozrejme si podobným spôsobom môžeme naprogramovať iné aspekty našej aplikácie a pripojiť ich do mechanizmu. V našej aplikécii sa začne diať mágia :-) Tieto listenery musíme zapojiť do NHibernate konfigurácie ešte pred požiadaním o konštrukciu ISessionFactory.

Implementácia našej vlastnej attribúty je jednoduchá, stačí (ako pri každej vlastnej atribúte) vytvoriť uzavretú - sealed - triedu dediacu od System.Attribute a dodať tých pár základných riadkov. Komentár utratím už len na nôtu tohto riadku:
[AttributeUsage(AttributeTargets.Property, AllowMultiple=false)]
Obmedzíme použitie našej atribúty na vlastnosti (čiže aby sme nimi neokrašľovali triedy / metódy atď.) a tiež aby sa mohla uplatniť len jedna atribúta thoto typu na jednu vlatnosť (property). Bol by to chaos, keby môžeme anotovať vlastnosť dvoma protichodnými atribútami:

[AutoUpdatedTimestamp]
[AutoUpdatedTimestamp(InsertOnly=true)]
public virtual DateTime MyProperty;

Náš zázračný listener by nevedel čo s takou vlastnosťou.

Náš listener TimestampOnInsertUpdate na prvých dvanástich riadkoch len implementuje metódy, ktoré musí, sú predpísané v IPreInsertEventListener / IPreUpdateEventListener interface-och. Z oboch metód zavolá magickú metódu AutoUpdateTimestamps a pošle jej to čo treba na celý trik. To sú argumenty entity, persister, state a isUpdate. Entity je náš modelový objekt ktorého stav sa snažíme vopchať do databázy. Persister je objekt zodpovedný za vykonanie samotného úkonu (emituje SQL príkaz(y)), state je aktuálny stav entity, ktorý NHibernate extrahoval z entity a pokúsi sa ho persistovať (uchovať v databáze) pomocou persisteru. Booleanská hodnota isUpdate len informuje o tom, či sa koná insert alebo update (potrebné pre vlastnosti kde atribúta má vlastnosť InsertOnly=true).

Riadok 15 získa z entity všetky vlastnosti typu DateTime. Riadok 16 prezrie tieto vlastnosti a vyberie z nich len tie, ktoré sme označili atribútou AutoUpdatedTimestamp. Ďalej, ak v tomto bode entita nemá žiadne pre-náš-listerner zaujímavé vlastnosti unikáme z metódy s návratovou hodnotou true - všetko OK - vybavené.

Ďalej, od riadku 22 sa venujeme tomu aby sme pri update-ovaní nemenili vlastnosti označené ako InsertOnly. Vyfiltrujeme ich preč, aby sme nemenili to čo nemáme.
Na riadku 32 sa znova pozrieme, či máme čo meniť, ak nie, padáme preč.

Ďalej už je takmer všetko jasné: zaobstaráme si timestamp (r.35) a ideme na vec - každej vhodnej vlastnosti zmeníme hodnotu na aktuálnu časovú známku (1.)priamo na entite r.41, (2.) v stave entity (argument state), ktorý bude persisterom zapísaný do databázy r.40.

Na zmenu stavu entity si zavoláme na pomoc malú metódku r.51, ktorá za pomoci informácií o persisterovi nastaví správnu časť objeku state na patričnú hodnotu.
Krok na riadku 41 je veľmi dôležitý: ako vysvetľuje stránka uvedená na spodku tohto článku, vynechaním tohto kroku by sme si mohli privodiť veľa veľa starostí debugovaním ťažko nájditeľných problémov. Hoci na databázovom servri by sme mali časovú známku nastavenú správne, nebola by v synchróne so stavom našej entity (náš objektový model by nebol zhodný s modelom persistovaným v našej databáze), čo by očividne mohlo napáchať škodu v rámci aplikácie. (Alebo aj nie, ak máme šťastie... radšej ani neskúšajme.)

A to je všetko. Je to v podstate celé jednoduché ako detská hračka, len človek sa samozrejme nenarodil s inštinktívnou znalosťou NHibernate a C#, tak si pomáhame blogmi ako tento. Dúfam, že som niekomu pomohol. Happy coding!

Niektoré časti tejto implementácie boli založené na kóde nájdenom v tomto
článku: Ayende Rahien a jeho článok o IPreInsertEventListener a IPreUpdateEventListener

Číslovanie Riadkov Textu

Práve som sklepal úplne jednoduchú utilitku na očíslovanie riadkov textu. Som strácal nervy na internete, snažil som sa nájsť nejakú on-line javascriptovú chujovinu čo by toto pre mna urobilo, ale napokon som sa odhodlal si to za 10 minut sklepať sám. Nájdete ju tu.

Nad kvalitou kódu som dlho hlavu nelámal, tak pardón, že to je dosť suboptimálne. Kód nasleduje:
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Add Line Numbers</title>
    <script type="text/javascript">
        function addLineNumbers(){
                var el = document.getElementById('input-text');
                var str = el.value;
                var lines = str.split('\n');
                var output = "";
                for(var i = 0; i<lines.length; i++)
                {
                    output += "" + (i+1) + "\t" + lines[i]+'\n';
                }
                el.value = output;
        }
    </script>
  </head>
  <body>
  <button onclick="javascript:addLineNumbers();">Add Line Numbers</button><br/>
    <textarea id="input-text" cols="80" rows="40"></textarea><br/>
  </body>
</html>

sobota 4. decembra 2010

Označenie položky v ListBoxe pomocou písania priamo do ListBoxu

Stiahnite si celý kód k spomínanej aplikácii 

Mnohokrát si užívateľ musí vybrať jednu položku z množstva v ponuke ListBox alebo ComboBox a je to nesmierne uľahčenie života, keď môže označiť požadovanú vec zo zoznamu priamym zadaním jednotlivých
písmen. Teda napríklad pri výbere krajiny zo zoznamu všetkých krajín sveta v ComboBoxe je najjednoduchšie označiť ComboBox a začať vyťukávať Slove... a to by už malo stačiť na označenie položky „Slovensko“ v zozname.

Nedávno som si naprogramoval malú utilitku na prehľadávanie (atď.) prednastavených farieb ktoré sú nadefinované v triede System.Windows.Media.Colors. Do ListBoxu som potom nasypal jednotlivé farby napojením ItemsSource na ObservableCollection triedy ColorVM (ktorá zastáva ViewModel jednotlivých farieb). Stiahnite si celý kód k spomínanej aplikácii


Nastavil som DataTemplate pre datový typ ColorVM aby jednotlivé objetky boli zobrazované v ListBoxe (a všade inde) ako obdĺžnik farebnej vzorky, vedľa ktorého je umiestnený text s názvom farby.
<DataTemplate DataType="{x:Type local:ColorVM}" >...

Takto nadefinovaný DataTemplate v App.xaml zaručuje že všetky objekty typu ColorVM v rámci aplikácie budú zdieľať rovnaký vzhľad. Prichystal som si aj políčko do ktorého užívateľ môže vpísať časťi názvu farbieb a ListBox sa podľa zadaného textu prefiltruje. Avšak, po označení ListBoxu som si všimol, že
sa nedajú označovať farby v ňom jednoduchým vyťukávaním názvu farby. Teda, ak by som dal Focus ListBoxu na obrázku, a začal vyťukávať „Toma“, položka s farbou „Tomato“ by sa neoznačila automaticky.

Ako teda donútiť ListBox (alebo ComboBox) aby označoval položky ako sme na to zvyknutí? ListBox v mojom príklade obsahuje objekty typu ColorVM a automatické označovanie položiek vieme že funguje pri
zoznamoch, v ktorých sú textové položky. Jednoduché riešenie teda aby aj náš zoznam sa dal prehľadávať automaticky postupným zadávaním písmen od začiatku slova nasleduje:

Stačí aby dátový typ jednotlivých položiek prekryl (override) metódu ToString. Keďže moja trieda ColorVM mala vlastnosť (property) Name, stačilo triedu ColorVM obohatiť o nasledovný kód:
public override string ToString()
{
return Name;
}
 
A hneď sa položky v našom ListBoxe dajú označovať automaticky vpísaním niekoľkých začiatočných písmen.

Stiahnite si celý kód k spomínanej aplikácii

piatok 3. decembra 2010

NHibernate - konfigurácia a chytáky

Práve sa mi podarilo prísť na to, prečo mi môj malý skúšobný programík s NHibernate nechcel ani za svet fungovať. Prv než zabudnem ako som problém vyriešil a na čo všetko som cestou k riešeniu naďabil, chcel by som si o tom urobiť záznam.
Problém spočíval v tom, že nech som sa snažil ako som sa snažil, stále NHibernate vyhadzoval chybu "NHibernate.MappingException: No persister for <class name>".
Užil som si pekné trápenie hľadaním problému. Preliezol som internet krížom-krážom a našiel viacero možných príčin pre toto chybové hlásenie, ale "no joy". Dosť frustrujúci bol fakt, že v práci pracujem na projekte, kde úspešne mapujem s NHibernate a všetko klape. Prezrel som niekoľko hodín video tutoriálov, prečítal niekoľko kratších aj dlhších textov na NHibernate/Hibernate a už-už som si začínal myslieť, že všetkému rozumiem, keď tu som doma narazil hlavou do steny a nemohol som sa s NHibernate ani pohnúť. Neustále sa NHibernate sťažovalo na "No persister for..."

Možné príčiny chyby NHibernate.MappingException
Message: No persister for <class name>

 

Chýba mapovací súbor (mapping file)

Proste ste ho ešte nevytvorili alebo ste ho vytvorili mimo Visual Studio a nepridali ste mapovací súbor do svojho projektu pomocou Solution Explorer-u.

Možné riešenia
Uistite sa, že teda naozaj mapovací súbor pre danú entitu máte v projekte. Je to XML súbor s názvom v tvare "MenoMapovanejEntity.hbm.xml". Pokiaľ sa nemýlim, v názve súboru ne*musí* byť meno mapovanej entity, ale musí mať koncovku ".hbm.xml" (hibernate mapping.xml). V jednom mapovacom XMLku môžete mať zmapovaných niekoľko entít naraz, ale neodporúča sa to, aby ste sa potom vyhli chaosu.
Pokiaľ tento súbor existuje niekde v zložkách projektu, skontrolujte ešte či vo Visual Studiu váš projekt zahŕňa tento súbor. V Solution Exploreri kliknite na ikonku Show All Files, navigujte k mapovaciemu súboru, urobte jeden pravý klik :-) a zvoľte Include in Project.

 

Build Action nastavená na Content

Jeden z ďalších dôvodov prečo sa vám NHibernate môže stále sťažovať, že No persister for... môže byť práve taký, že hoci mapovací súbor máte, aj je Included vo vašom projekte, jeho Build Action je ešte stále nastavená na "Content".

Riešenie
Toto musíte v okne Properties zmeniť na Embedded Resource, aby sa váš xml súbor vkompiloval do výstupného .dll alebo .exe. Skontrolujte si, či ste nastavili Embedded resource pre všetky vaše .hbm.xml mapping files.

 

NHibernate konfigurácia nevie v ktorej knižnici (assembly) má hľadať mapovacie info

Ďalšia často odporúčaná rada pri problémoch tohto typu je pridať element mapping do session-factory konfigurácie v NHibernate konfiguračnej sekcii vášho app.config súboru (ak teda je vaša NHibernate konfigurácia umiestnená práve tam).

Riešenie
Vlastne, pokiaľ ste si zvolili metódu konfigurácie založenú na XML, tak je jedno ci máte nastavenia v nejakom zvlášť súbore, či v ako sekciu v app.config. Budete v nich potrebovať element mapping.

<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
   <session-factory>
      <property name="... />
      ...
      <mapping assembly="Kniznica"/>
   </session-factory>
</hibernate-configuration>
Tento element uvediete v poradí až posledný, každopádne po všetkých "property" elementoch, ktoré nastavujú NHibernate session factory. Nič viac v ňom nie je potrebné, len názov knižnice (assembly), ktorá obsahuje mapované triedy a do ktorej sú vkompilované mapovacie súbory .hbm.xml. NHibernate to pomôže v tom, že bude pri zavolaní metódy Configure() vedieť ktorej knižnice sa ujať a prezrieť jej metadata.

 

NHibernate.Cfg.Configuration objekt nie je nakonfigurovaný

Tento problém ma strašil niekoľko hodín. Kôli tomuto som sa vlastne odhodlal napísať tento článok. Aj keď máte úplne všetko pre NHibernate nastavené tak ako sa patrí a všetky mapovania máte namapované správne a pozapájané do svojho projektu podľa všetkých múdrych rád, stále je šanca že vám nič z toho nebude fungovať a že sa vám NHibernate stále bude sťažovať, že No persister for... Ešte aj Stack Trace je zavádzajúci. Popreklínal som si tvorcov NHibernate dosť keď som zistil v čom bol problém.

Riešenie
Problém môže byť v tom ako si vytvárate NHibernate ISessionFactory. Tak napríklad mne sa podarilo nasledovné:
var nhConfig = new NHibernate.Cfg.Configuration();
ISessionFactory sessionFactory = nhConfig.BuildSessionFactory();
Problém spočíval v tom, že hoci som svoj nový objekt NHibernate kofigurácie vytvoril, nenakonfiguroval som ho zavolaním metódy Configure(). Možno mi jedného dňa niekto vysvetlí, prečo volanie funkcie BuildSessionFactory v nanakofigurovanom stave nevedie k InvalidOperationException. Hore-uvedený kód krásne funguje, teda okrem toho, že pri prvom pokuse o získanie perzistentnej entity cez interface ISession (volaním metódy Load, Get, etc...) sa NHibernate sťažuje na No persister for... Kôli tomuto čudesnému správaniu som zabil niekoľko hodín vŕtaním sa v mojom kóde a prezeraním konfigurácií a mapovacích súborov a vlastností projektových súborov. Pri tom jediné, čo bolo treba urobiť pre odstránenie problému, bolo zavolať Configure() na objekte Configuration skôr než ho požiadame o vytvorenie ISessionFactory.
var nhConfig = new NHibernate.Cfg.Configuration().Configure();
Paráda, tak a je po problémoch. Kto narazí na NHibernate.MappingException so správou "No persister for..." a má v projekte všetko podľa vyššie uvedených rád, ozvite sa mi, rád sa pokúsim pomôcť, resp. ak máte riešenie, tak popis problému aj s riešením môžeme pripísať na zoznam.
Veselé kódovanie!