/hazelcast-documentation/src/main/docbook/manual/content/j2ee/JEEIntegration.xml
XML | 264 lines | 242 code | 7 blank | 15 comment | 0 complexity | 20b37856568fff2fa4b7b8f6a17ccc4d MD5 | raw file
1<?xml version='1.0' encoding='UTF-8'?> 2<!-- 3 ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved. 4 ~ 5 ~ Licensed under the Apache License, Version 2.0 (the "License"); 6 ~ you may not use this file except in compliance with the License. 7 ~ You may obtain a copy of the License at 8 ~ 9 ~ http://www.apache.org/licenses/LICENSE-2.0 10 ~ 11 ~ Unless required by applicable law or agreed to in writing, software 12 ~ distributed under the License is distributed on an "AS IS" BASIS, 13 ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 ~ See the License for the specific language governing permissions and 15 ~ limitations under the License. 16 --> 17 18<sect1 xml:id="JEEIntegration" version='5.0' xmlns='http://docbook.org/ns/docbook' 19 xmlns:xi="http://www.w3.org/2001/XInclude" 20 xmlns:xlink="http://www.w3.org/1999/xlink" 21 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 22 xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd 23 http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"> 24 <title>J2EE Integration</title> 25 <para>Hazelcast can be integrated into J2EE containers via Hazelcast Resource Adapter ( 26 hazelcast-ra.rar ). After proper configuration, Hazelcast can participate in standard J2EE 27 transactions. 28 <programlisting language="java"><![CDATA[<%@page import="javax.resource.ResourceException" %> 29<%@page import="javax.transaction.*" %> 30<%@page import="javax.naming.*" %> 31<%@page import="javax.resource.cci.*" %> 32<%@page import="java.util.*" %> 33<%@page import="com.hazelcast.core.Hazelcast" %> 34 35<% 36UserTransaction txn = null; 37Connection conn = null; 38Config cfg = new Config(); 39HazelcastInstance hz = Hazelcast.newHazelcastInstance(cfg); 40Queue queue = hz.getQueue ("default"); 41Map map = hz.getMap ("default"); 42Set set = hz.getSet ("default"); 43List list = hz.getList ("default"); 44 45try { 46 Context context = new InitialContext(); 47 txn = (UserTransaction) context.lookup("java:comp/UserTransaction"); 48 txn.begin(); 49 50 ConnectionFactory cf = (ConnectionFactory) context.lookup ("java:comp/env/HazelcastCF"); 51 conn = cf.getConnection(); 52 53 queue.offer("newitem"); 54 map.put ("1", "value1"); 55 set.add ("item1"); 56 list.add ("listitem1"); 57 58 txn.commit(); 59} catch (Throwable e) { 60 if (txn != null) { 61 try { 62 txn.rollback(); 63 } catch (Exception ix) {ix.printStackTrace();}; 64 } 65 e.printStackTrace(); 66} finally { 67 if (conn != null) { 68 try { 69 conn.close(); 70 } catch (Exception ignored) {}; 71 } 72} 73%> 74]]></programlisting> 75 </para> 76 <sect2 xml:id="JEEIntegrationConfig" version='5.0' xmlns='http://docbook.org/ns/docbook' 77 xmlns:xlink='http://www.w3.org/1999/xlink' 78 xmlns:xi='http://www.w3.org/2001/XInclude' 79 xmlns:ns5='http://www.w3.org/2000/svg' 80 xmlns:ns4='http://www.w3.org/1998/Math/MathML' 81 xmlns:ns3='http://www.w3.org/1999/xhtml' 82 xmlns:db='http://docbook.org/ns/docbook'> 83 <title>Resource Adapter Configuration</title> 84 <para>Deploying and configuring Hazelcast resource adapter is no different than any other 85 resource adapter since it is a standard 86 <literal>JCA</literal> 87 resource adapter but 88 resource adapter installation and configuration is container specific, so please consult 89 your J2EE vendor documentation for details. Most common steps are: 90 <orderedlist> 91 <listitem> 92 <para>Add the 93 <literal>hazelcast.jar</literal> 94 to container's classpath. Usually 95 there is a lib directory that is loaded automatically by the container on 96 startup. 97 </para> 98 </listitem> 99 <listitem> 100 <para>Deploy<literal>hazelcast-ra.rar</literal>. Usually there is a some kind of 101 deploy directory. Name of the directory varies by container. 102 </para> 103 </listitem> 104 <listitem> 105 <para>Make container specific configurations when/after 106 deploying<literal>hazelcast-ra.rar</literal>. Besides container specific 107 configurations, 108 <literal>JNDI</literal> 109 name for Hazelcast resource is 110 set. 111 </para> 112 </listitem> 113 <listitem> 114 <para>Configure your application to use the Hazelcast resource. Updating 115 <literal>web.xml</literal> 116 and/or 117 <literal>ejb-jar.xml</literal> 118 to let 119 container know that your application will use the Hazelcast resource and 120 define the resource reference. 121 </para> 122 </listitem> 123 <listitem> 124 <para>Make container specific application configuration to specify 125 <literal>JNDI</literal> 126 name used for the resource in the application. 127 </para> 128 </listitem> 129 </orderedlist> 130 </para> 131 </sect2> 132 <sect2 xml:id="JEEIntegrationGlassfishSample" version='5.0' xmlns='http://docbook.org/ns/docbook' 133 > 134 <title>Sample Glassfish v3 Web Application Configuration</title> 135 <para> 136 <orderedlist> 137 <listitem> 138 <para>Place the 139 <literal>hazelcast-<version>.jar</literal> 140 into 141 <literal>GLASSFISH_HOME/glassfish/domains/domain1/lib/ext/</literal> 142 directory. 143 </para> 144 </listitem> 145 <listitem> 146 <para>Place the 147 <literal>hazelcast-ra-<version>.rar</literal> 148 into 149 <literal>GLASSFISH_HOME/glassfish/domains/domain1/autodeploy/</literal> 150 directory 151 </para> 152 </listitem> 153 <listitem> 154 <para>Add the following lines to the 155 <literal>web.xml</literal> 156 file. 157 <programlisting language="xml"><![CDATA[<resource-ref> 158 <res-ref-name>HazelcastCF</res-ref-name> 159 <res-type>com.hazelcast.jca.ConnectionFactoryImpl</res-type> 160 <res-auth>Container</res-auth> 161</resource-ref> 162]]></programlisting> 163 </para> 164 </listitem> 165 </orderedlist> 166 Notice that we didn't have to put 167 <literal>sun-ra.xml</literal> 168 into the 169 rar file because it comes with the 170 <literal>hazelcast-ra-<version>.rar</literal> 171 file already. 172 </para> 173 <para>If Hazelcast resource is used from EJBs, you should configure 174 <literal>ejb-jar.xml</literal> 175 for resource reference and 176 <literal>JNDI</literal> 177 definitions, just like we did for<literal>web.xml</literal>. 178 </para> 179 </sect2> 180 <sect2 xml:id="JEEIntegrationJBossSample" version='5.0' xmlns='http://docbook.org/ns/docbook' 181 > 182 <title>Sample JBoss Web Application Configuration</title> 183 <para> 184 <itemizedlist> 185 <listitem> 186 <para>Place the 187 <literal>hazelcast-<version>.jar</literal> 188 into 189 <literal>JBOSS_HOME/server/deploy/default/lib</literal> 190 directory. 191 </para> 192 </listitem> 193 <listitem> 194 <para>Place the 195 <literal>hazelcast-ra-<version>.rar</literal> 196 into 197 <literal>JBOSS_HOME/server/deploy/default/deploy</literal> 198 directory 199 </para> 200 </listitem> 201 <listitem> 202 <para>Create a 203 <literal>hazelcast-ds.xml</literal> 204 at 205 <literal>JBOSS_HOME/server/deploy/default/deploy</literal> 206 directory 207 containing the following content. Make sure to set the 208 <literal>rar-name</literal> 209 element 210 to<literal>hazelcast-ra-<version>.rar</literal>. 211 <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> 212<!DOCTYPE connection-factories 213 PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN" 214 "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> 215 216<connection-factories> 217 <tx-connection-factory> 218 <local-transaction/> 219 <track-connection-by-tx>true</track-connection-by-tx> 220 <jndi-name>HazelcastCF</jndi-name> 221 <rar-name>hazelcast-ra-<version>.rar</rar-name> 222 <connection-definition> 223 javax.resource.cci.ConnectionFactory 224 </connection-definition> 225 </tx-connection-factory> 226</connection-factories> 227]]></programlisting> 228 </para> 229 </listitem> 230 <listitem> 231 <para>Add the following lines to the 232 <literal>web.xml</literal> 233 file. 234 <programlisting language="xml"><![CDATA[<resource-ref> 235 <res-ref-name>HazelcastCF</res-ref-name> 236 <res-type>com.hazelcast.jca.ConnectionFactoryImpl</res-type> 237 <res-auth>Container</res-auth> 238</resource-ref> 239]]></programlisting> 240 </para> 241 </listitem> 242 <listitem> 243 <para>Add the following lines to the 244 <literal>jboss-web.xml</literal> 245 file. 246 <programlisting language="xml"><![CDATA[<resource-ref> 247 <res-ref-name>HazelcastCF</res-ref-name> 248 <jndi-name>java:HazelcastCF</jndi-name> 249</resource-ref> 250]]></programlisting> 251 </para> 252 </listitem> 253 </itemizedlist> 254 If Hazelcast resource is used from EJBs, you should configure 255 <literal>ejb-jar.xml</literal> 256 and 257 <literal>jboss.xml</literal> 258 for resource 259 reference and 260 <literal>JNDI</literal> 261 definitions. 262 </para> 263 </sect2> 264</sect1>