Project

General

Profile

How to Spring » History » Revision 24

Revision 23 (Henning Blohm, 07.09.2012 12:57) → Revision 24/62 (Henning Blohm, 07.09.2012 12:57)

h1. How to Use the Spring Framework in Z2 

 There is actually nothing sooo particular about using Spring in Z2. But when knowing how Z2 modularity works, there is much to gain by spending a few minutes reading this Howto. However it is required that you are familiar with the Spring framework as such. 

 h2. Pre-Requisites 

 In order to have the Spring libraries available you need to add the repository _z2-addons.spring_ to your environment. Some samples, for example the z2-samples.jta-spring sample explained in [[How to TransactionManager]] does so. To use the master branch version, add a *springRepository.properties* component descriptor to your *environment* module saying 

 <pre><code class="python"> 
 com.zfabrik.systemStates.participation=com.zfabrik.boot.main/sysrepo_up 

 # git stored component repository 
 com.zfabrik.component.type=com.zfabrik.gitcr 

 # true <=> optional repository. If gitcr.uri is invalid, then this gitcr will be ignore silently   
 gitcr.optional=true 

 # this can also point to a remote repository like  
 # ssh://myserver/some/git/repo 
 gitcr.uri=http://git.z2-environment.net/z2-addons.spring 

 # the git branch to use (e.g. 'master') 
 gitcr.branch=master 
 </code></pre> 

 For your own system, you may need to adapt the repository URL and the branch selection accordingly. 

 If that sounds like meaningless gibberish to you - sorry please consult the documentation at http://www.z2-environment.eu/v20doc and go back to [[First_steps_with_z2]]. 


 When you added that repository the following modules are available: 

 * org.springframework.orm 
 * org.springframework.security 
 * org.springframework.foundation    
 * org.springframework.transaction 
 * org.springframework.jdbc          
 * org.springframework.web 
 * com.zfabrik.springframework       
 * com.zfabrik.springframework.web   


 With the exception of those starting with "com.zfabrik", these do, more or less, correspond to the typical Spring modules found out there.  

 Before you get frustrated by the amount of details in this Howto, please remember that there is practical samples available to help you check how things can really be assembled to work nicely: 

 * z2-samples.jta-spring (LINK) 

 h2. Using Spring in Web Applications 

 This is the simplest and really just the standard case. If you do not strive for re-use across modules that use Spring, then there is not much to worry about.  

 As usual, you define an application context in the WEB-INF folder of the Web application and set up a context listener in WEB-INF/web.xml to have the application  
 context initialized as the Web app is started. 

 In order to have the minimal set of dependencies satisfied - i.e. not assuming you want to use the (very cool) AspectJ based Spring configuration, you should _add_ (i.e. augment whatever refs you already have) the following references to *java/z.properties*: 

 <pre><code class="python"> 
 java.privateReferences=\ 
	 com.zfabrik.springframework.web,\ 
	 org.springframework.foundation,\ 
	 org.springframework.web 

 </code></pre> 

 The reference to *com.zfabrik.springframework.web* is not strictly needed but adds the following capabilities: 

 * You implicitly get *com.zfabrik.springframework*, i.e. the integration features described below 

 * You can use a parent application context to your Web application application context as easily as you would hope (see below). 


 h2. Using Spring Context Support 

 The module *org.springframework.foundation* holds a Java component *org.springframework.foundation/context.support* that is not meant to be referenced but to be _included_. 
 Including a Java component means that it's resources (class files, jars,...) will be copied into the including scope rather than referenced via class loader delegation. 

 The difference is that in that case, all the includer sees is also be seen by the types in the included component. And that is exactly what context.support is about: It holds adapter classes that effectively have dangling dependencies on other prominent libraries. Say for example we are talking about the Lucene search engine library. If your Java component references the Lucene libs (which are not included with Z2 by default), and say you want to use the Spring adapter types, then include context.support by adding (i.e. customizing correspondingly) the private include: 

 <pre><code class="python"> 
 java.privateIncludes=\ 
    org.springframework.foundation/context.support 
 </code></pre> 

 Typically it makes most sense to only use _private includes_. If you include into the API, which is possible, other modules that reference your API will find the included types 
 of your API with preference of their includes (as part of the parent-first delegation principle). So, they may not be able to repeat the same include pattern described above.  

 h2. Using Spring in Re-use Modules 

 When going modular, you will leave the pure "Spring in a Web Application" path. That is, you may want to use Spring in modules that expose components and APIs to other modules. For example to implement shared services that are used in more than one Web Application, or for example to implement scheduled job execution. 

 *Define an Application Context in a Java Module* 

 In that case, you will not define an application context in a WEB-INF folder (as there most likely is none) but instead you will define a class path defined application context, or more specifically you will put your application context (most likely) in *java/src.impl/META-INF/applicationContext.xml* of your re-use module. 

 *Starting an Application Context* 

 Now that you have that application context, you need to make sure it is started. If you went this far, there is good reasons you use Z2 runtime dependencies to start it. Pre-requisite for that is to have the application context declared as a Z2 component. So you create a file *applicationContext.properties* in your module saying 

 <pre><code class="python"> 
 com.zfabrik.component.type=org.springframework.context 

 # 
 # context config location is where the context is  
 # actually defined.  
 # 
 context.contextConfigLocation=classpath:META-INF/applicationContext.xml 
 </code></pre> 

 Once it is defined as a component, you can have it started via a "system state dependency":http://www.z2-environment.eu/v20doc#System%20States%20(core), via a "generic component depencency":http://www.z2-environment.eu/v20doc#CoreComponentProps. 

 Another way is to have it started implicitly from a bean component declaration. In that case, before providing the bean instance, the application context will be initialized. 

 *Exposing a Bean from an Application Context* 

 Now that you have declared an application context component, you can actually expose beans from it as Z2 components that may be looked up from other modules. To do so, create a component like this: 

 <pre><code class="python"> 
 com.zfabrik.component.type=org.springframework.bean 

 # 
 # the context that defines the bean (more than one 
 # bean can be exposed like this) 
 # 
 bean.context=<module name>/applicationContext bean.context=&lt;module name&gt;/applicationContext 

 # 
 # the bean name 
 # 
 bean.name=&lt;bean name&gt; 
 </code></pre> 

 Now that a bean has been made available to other modules, the next natural question is how to actually refer to a Z2 component from a Spring application context. 

 *Importing a Bean Or Just Any Component* 




 h2. Using Spring's Aspect/J Configuration 

 h2. Using a Parent Application Context in a Web Application Application Context 

 Sometimes, later, when you find that your module has a web app but in addition you want to expose services, from the very same module, i.e. when you have spring configured objects in the web app but also a classpath defined application context that should serve as a _parent application context_ to the one of the web app (admittedly an advanced case), then you will find that that is slightly tricky to achieve (see e.g. http://blog.springsource.org/2007/06/11/using-a-shared-parent-application-context-in-a-multi-war-spring-application/).  

 The class *com.zfabrik.springframework.web.ComponentParentContextContextLoaderListener* is a drop-in replacement for Spring's ContextLoaderListener implementation that simplifies that use-case as explained in http://z2spring.z2-environment.net/javadoc/com.zfabrik.springframework.web!2Fjava/api/com/zfabrik/springframework/web/ComponentParentContextContextLoaderListener.html.