PageRenderTime 16ms CodeModel.GetById 10ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/hazelcast-documentation/src/main/docbook/manual/content/j2ee/JEEIntegration.xml

https://bitbucket.org/gabral6_gmailcom/hazelcast
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-&lt;version&gt;.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-&lt;version&gt;.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-&lt;version&gt;.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-&lt;version&gt;.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-&lt;version&gt;.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-&lt;version&gt;.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>