Spring framework: konfigurace transakcí v XML pomocí TransactionInterceptor

Dnes jsem kolegovi vysvětloval jak se definují transakce v XML a myslím, že je to natolik častá činnost, že se tato informace bude hodit více lidem. Hned na začátek podotýkám, že zde budu popisovat pouze jeden z možných způsobů konfigurace. Praxe mě naučila, že Spring framework nabízí více možností jak určité věci řešit a nejinak tomu je i zde. Dále se budu zabývat pouze možností konfigurace pomocí XML a to pomocí třídy TransactionInterceptor a BeanNameAutoProxyCreator. Tato konfigurace je zejména vhodná pro Spring framework ve verzi 1.2.x, protože ve verzi 2.x se možnosti značně rozšířily (možnost anotací, XML tagy přímo pro definici transakcí, AOP)

Nechci zde duplikovat informace uvedené v javadoc Springu, mojí snahou je spíše uvést skutečnosti, které na první pohled nemusí být zřejmé.

V rámci konfigurace transakcí je možné definovat (nejenom) následující parametry chování transakce:

• propagace transakce - nejčastěji používané hodnoty jsou PROPAGATION_REQUIRED, PROPAGATION_REQUIRES_NEW a PROPAGATION_SUPPORTS.


• readOnly (volitelné) - zda se jedná o transakcí, která bude pouze číst. Zda se tento parametr využije závisí na zvoleném typu propagace transakce a na použitém transakčním manažeru.


• -Exceptions - vyjímky (oddělené čárkou), při kterých dojde k roll-backu transakce (volitelné). Pokud není uvedena žádná vyjímka v definici, tak se předpokládá vyjímka typu RuntimeException, ne Exception.


• +Exceptions - vyjímky (oddělené čárkou), při kterých daná transakce projde. Takové vyjímky mezi vyjímkami :-)

Pouze první parametr je povinný. Jednotlivé parametry se oddělují čárkou. Definice může tedy vypadat třeba následovně: PROPAGATION_REQUIRED,readOnly,-Exception,+UnsupportedMethodCallException,+OperationAlreadyFinishedException.

Všechny tyto parametry a spousta dalších věcí okolo transakcí ve Springu jsou velice pěkně popsány v tomto článku.

Třída TransactionInterceptor má následující settery:

• setTransactionManager() pro nastavení manažera, který provádí vlastní management transakcí. Např. pro Hibernate je to HibernateTransactionManager. Pro různé manažery (Hibernate, JDBC, JCR) můžeme mít různé požadavky na transakce, proto je tedy konfigurace parametrů transakce vztažena vždy k jednomu transakčnímu manažerovi.


• setTransactionAttributes() - nastavení metod a parametrů transakcí pomocí Properties, kde klíč je jméno metody a hodnota obsahuje parametry transakce. Zde je nutné poznamenat, že toto nastavení je interně zpracováno třídou NameMatchTransactionAttributeSource. Na tento setter se dá tedy nahlížet jako na pomocnou metodu pro uživatele, protože používá nejčastěji používanou implementaci pro zápis metod.


• setTransactionAttributeSource() - nastavení transakcí dle vlastní volby. Možné volby jsou dány rozhraním TransactionAttributeSource a jeho implementacemi. V úvahu pro XML zápis připadají tyto implementace:
  • MatchAlwaysTransactionAttributeSource - jednoduchá implementace, která nastavuje stejné transakční parametry bez ohledu na metody
  
  
  • MethodMapTransactionAttributeSource - vhodné pro definice transakcí, kde nám jde o vyjádření metod pomocí plných jmen (FQCN), tedy pomocí plné cesty k dané třídě nebo rozhraní a jménu metody. Je možné používat i zástupný znak * v názvu metody. Pak to funguje tak, že Spring si během inicializace automaticky doplní interní seznam metod o plné názvy metod, které odpovídají zápisům s hvězdičkou. Přesněji specifikovaný zápis metody přebijí volnější definici s hvězdičkou.
  
  
  • NameMatchTransactionAttributeSource - nejčastěji používaná implementace, která umožňuje definovat pravidla pro zachytávání metod velice volně pomocí hvězdičkové notace (např. "xxx*", "*xxx" or "*xxx*"). Zde to funguje trochu jinak než u předchozí implementace - až teprve při spouštění metody se Spring snaží dle definovaných pravidel najít správný záznam, který lze použít a pokud ho najde, tak nastaví transakci dle definovaných parametrů.


• setTransactionAttributeSources() - variace na předchozí setter. Tato volba je vhodná pro nastavení transakcí více způsoby. Toto se může hodit celkem často, protože co lze vyjádřit jedním způsobem zápisu již nelze tak dobře vyjádřit jiným způsobem.

Dle mé zkušenosti nefunguje kombinace metod setTransactionAttributes() a setTransactionAttributeSource(). Pokud uživatel potřebuje nadefinovat transakce pomocí více způsobů, tak by měl použít metodu setTransactionAttributeSources.

Nakonec dvě ukázky - první je příklad nejčastějšího použití, druhý příklad ukazuje definici pomocí složitější konstrukce.

  <bean id="DbTransactionInterceptor"
    class="org.springframework.transaction.interceptor.TransactionInterceptor">
    <property name="transactionManager" ref="dbTransactionManager" />
    <property name="transactionAttributes">
      <props>     
        <prop key="get*">PROPAGATION_REQUIRED,readOnly</prop>
        <prop key="search*">PROPAGATION_REQUIRED,readOnly</prop>
        <prop key="exist*">PROPAGATION_REQUIRED,readOnly</prop>
        <prop key="add*">PROPAGATION_REQUIRED,-Exception</prop>
        <prop key="remove*">PROPAGATION_REQUIRED,-Exception</prop>
        <prop key="change*">PROPAGATION_REQUIRED,-Exception</prop>
       
        <prop key="cz.anect.mis.web.facade.DocumentFacade.getAdminsByLocation">PROPAGATION_REQUIRED,readOnly</prop>        
        <prop key="cz.anect.mis.web.facade.DocumentFacade.addDocumentOnlineRequest">PROPAGATION_REQUIRED,-Exception</prop>
        
      </props>
    </property>
  </bean>

  <bean id="DbTransactionInterceptor" class="org.springframework.transaction.interceptor.TransactionInterceptor">
    <property name="transactionManager" ref="dbTransactionManager"/>
    <!-- full qualified method names -->
    <property name="transactionAttributeSource">
      <bean class="org.springframework.transaction.interceptor.MethodMapTransactionAttributeSource">
        <property name="methodMap">
          <map>
            <entry key="cz.anect.mis.services.DocumentService.addDocument" value="PROPAGATION_REQUIRED,-Exception" />
            <entry key="cz.anect.mis.services.DocumentService.addDocumentToData" value="PROPAGATION_REQUIRED,-Exception" />            
            <entry key="cz.anect.mis.web.facade.DocumentFacade.addDocumentData" value="PROPAGATION_REQUIRED,-Exception" />
            <entry key="cz.anect.mis.web.facade.DocumentFacade.get*" value="PROPAGATION_REQUIRED,readOnly" />
            <entry key="cz.anect.mis.web.facade.DocumentFacade.exist*" value="PROPAGATION_REQUIRED,readOnly" />
            <entry key="cz.anect.mis.web.facade.DocumentFacade.getDocumentByDownloadHash" value="PROPAGATION_REQUIRED,-Exception" />

            <entry key="cz.anect.mis.web.facade.CodelistFacade.addStorePlaceAndFund" value="PROPAGATION_REQUIRED" />
            <entry key="cz.anect.mis.web.facade.CodelistFacade.addNewDigiUser" value="PROPAGATION_REQUIRED" />
            <entry key="cz.anect.mis.web.facade.CodelistFacade.get*" value="PROPAGATION_REQUIRED,readOnly" />                        
          </map>
        </property>
      </bean>
    </property>
  </bean>

Aby byla konfigurace transakcí kompletní je nutné ještě dodefinovat propojení mezi transakčními "zachytávači" (TransactionInterceptor) a instancemi tříd, na které budeme transakční pravidla aplikovat.

  <bean id="BeanNameProxyCreator" class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
    <property name="beanNames">
      <list>
        <idref bean="DocumentFacade"/>
        <idref bean="CodelistFacade"/>        
        <idref bean="DocumentService"/>        
        <idref bean="PlaceIdentificationFacade"/>        
      </list>
    </property>
    <property name="interceptorNames">
      <list>
        <idref bean="DbTransactionInterceptor"/>
        <idref bean="JcrTransactionInterceptor"/>
        <idref bean="gisJdbcTransactionInterceptor"/>
      </list>
    </property>
  </bean>