Getting started with ZK CDI

{{Template:Smalltalk_Author|
|author=Ashish Dasnurkar, Engineer, Potix Corporation
|date=March 22, 2010
|version=ZK CDI 1.0RC
}}

<imagelink link="http://www.zkoss.org/download/zkcdi.dsp" image="http://docs.zkoss.org/images/6/69/DownloadNow.jpg" text="Download ZK CDI" />

==Introduction==

ZK CDI is based on the portable extension mechanism defined in JSR-299 of the Java EE 6 platform. It allows Java EE application developers to seamlessly leverage both ZK and CDI’s powerful set of features for developing enterprise applications.

In addition to the built in features of CDI, ZK CDI provides the following features:

*Custom variable resolver/EL resolver
*ZK custom scopes
*ZK components as managed beans
*UI event handlers using ZK custom annotation and CDI provided event notification model

=== Why ZK + CDI ===
ZK CDI provides seamless integration with CDI to expose CDI services within the ZK framework. It provides enterprise developers the ability to integrate CDI driven applications with a compressive and powerful Ajax front end supplied by ZK. Using CDI and ZK together makes bridging the gap between Java’s EE web tier and Java EE an effortless process.

==Getting started with ZK CDI==
===HelloWorld using ZK CDI Demo===
<gflash width="256" height="101">Zkcdi_helloworld.swf</gflash>

=====Variable resolver=====

<source lang="xml">
--index.zul--

<?page title="HelloWorld" contentType="text/html;charset=UTF-8"?>
<?variable-resolver class="org.zkoss.zkplus.cdi.DelegatingVariableResolver"?>
<zk>
<window id="helloWindow" title="HelloWorld" border="normal" width="250px" apply="${helloWorld} ">
<textbox id="guestName" width="150px" />
<button id="sayHelloBtn" label="Say hello"/>
</window>
</zk>
</source>

ZK CDI extension provided variable resolver allows us to resolve CDI managed beans by their EL names. Here I use it to resolve HelloWorld controller by its EL name and apply to window component. Notice that HellowWorld is annotated with @Named annotation and according to JSR-299 CDI spec it will be by default resolved for "helloWorld" EL name.

===Writing controller class by extending GenericComposer with CDI support===
<source lang="java">
--HelloWorld.java--

@Named
@SessionScoped
public class HelloWorld extends GenericComposer implements Serializable {

	@Inject @ComponentId("guestName") Textbox guestName;
	@Inject @ComponentId("sayHelloBtn") Button sayHelloBtn;
	@Inject @ComponentId("helloWindow") Window helloWindow;
	
	public void sayHello(@Observes @Events("sayHelloBtn.onClick") MouseEvent evt) {
		helloWindow.setTitle("Hello " + guestName.getValue());
	}
}
</source>

ZK CDI extension comes with a abstract utility class which can be extended to write controller class that can leverage CDI injection of ZK components and event notification model to write intuitive event handler methods by observing specific event types.

=====ZK component injection in controller=====
In addition to EL resolver one can also use ZK CDI extension to inject child components into controller using @Inject annotation along with ZK CDI extension defined '''@ComponentId''' qualifier. In order to uniquely identify injection point for each child component ZK CDI extension needs to be provided with actual component ids as @CompoentId qualifier member value. In above example textbox, button and window components defined in index.zul file will be auto injected into HellowWorld controller bean instance. This is similar to GenericForwardComposer wiring composer variables with actual zul components.

=====Event handlers using ZK CDI custom qualifier=====
ZK CDI extension also defines '''@Events''' qualifier which allows us to define ZK UI event handlers by observing ZK Event types such as MouseEvent, SelectEvent etc. Here I defined onClick event handler for sayHelloBtn by observing on MouseEvent type. Whenever sayhellobtn is clicked ZK framework receives MouseEvent which is later published by ZK CDI extension using CDI event notification model. Any event handling method can @Observes this event type to receive notification and in turn be notified whenever this event type is published. Event handling methods are distinguished by @Events qualifier member values. Developers can also specify same event handler for multiple events separated by a comma in the @Events qualifier member value for example <source lang="javascript">
@Events("btn1.onclick,btn2.onClick")</source>In above example whenever sayHelloBtn is clicked MouseEvent will be sent to ZK framework which later will be published by ZK CDI extension with correct @Events qualifier value mentioning component id and event name for example sayHelloBtn.onClick. CDI framework then will notify any method that is observing for MouseEvent type and also has the same @Events qualifier member value.

==Setup development environment==

===Setup ZK  web application with ZK CDI support===
:1. Create a ZK web application project by following [[ZK Installation Guide]]. Note: ZK CDI extension works with latest ZK 5.0.1 release
:2. Download and copy [http://code.google.com/p/zkcdi/downloads/list zkcdi.jar] to your WEB-INF/lib in the web root folder. Zkcdi.jar should be used as a web application library.
:3. Download [http://code.google.com/p/reflections/downloads/list reflections-0.9.5-RC1.jar] from Reflections google code project. Also download all dependant jar files for this project. Copy all files to your web root/WEB-INF/lib folder

===Setup Weld with Tomcat===
:1. Download [http://seamframework.org/Download weld-servlet-1.0.1-Final.jar] and copy to your web root/WEB-INF/lib
:2. You also need to explicitly specify the servlet listener (used to boot Weld, and control its interaction with requests) in WEB-INF/web.xml in the web root:

<source lang="xml">
<listener>
   <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
</listener>
<listener>
   <listener-class>org.jboss.weld.el.WeldELContextListener</listener-class>
</listener>
</source>

:3. Tomcat has a read-only JNDI, so Weld can't automatically bind the BeanManager extension SPI. To bind the BeanManager into JNDI, you should populate META-INF/context.xml in the web root with the following contents:
<source lang="xml"><Context>
		<Resource name="BeanManager"
		auth="Container"
		type="javax.enterprise.inject.spi.BeanManager"
		factory="org.jboss.weld.resources.ManagerObjectFactory"/>
</Context>
</source>

:4. and make it available to your deployment by adding this to the bottom of web.xml
<source lang="xml">
<resource-env-ref>
		<resource-env-ref-name>BeanManager</resource-env-ref-name>
		<resource-env-ref-type>javax.enterprise.inject.spi.BeanManager</resource-env-ref-type>
</resource-env-ref>
</source>

:5. Add an empty beans.xml file under WEB-INF folder to enable dependency injection by CDI
Note: There are similar instructions available to setup Weld with other application servers & environments. 
Please refer to [http://docs.jboss.org/weld/reference/1.0.0/en-US/html/environments.html Using Weld in other application servers and environments] for more information on this.

==Real world example using ZK CDI==
IBM Developerworks has published a comprehensive article on ZK CDI. The article talks about all ZK CDI features in depth and also guides developers through a real world example code using ZK CDI. You can read it [http://www.ibm.com/developerworks/web/library/wa-aj-zkcdi/ here]

==References==
:1. [[ZK Installation Guide]]
:2. [http://code.google.com/p/zkcdi/ ZK CDI Google Code Project Home]
:3. [http://seamframework.org/Weld Weld Reference Implementation of JSR-299]
:4. [http://java.sun.com/developer/technicalArticles/JavaEE/JavaEE6Overview.html Java EE 6 platform Introduction]
:5. [http://docs.jboss.org/weld/reference/1.0.0/en-US/html/environments.html Using Weld in other application servers and environments]

[[Category:3rd Party Components]]
[[Category:Other Frameworks]]
{{Template:CommentedSmalltalk_Footer|
|name=Potix Corporation
}}