forked from spring-projects/spring-data-gemfire
-
Notifications
You must be signed in to change notification settings - Fork 0
/
data.xml
348 lines (286 loc) · 18.2 KB
/
data.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="apis">
<title>Working with the GemFire APIs</title>
<para>Once the GemFire cache and regions have been configured they can
injected and used inside application objects. This chapter describes the
integration with Spring's transaction management functionality and
<classname>DaoException</classname> hierarchy. It also covers support for
dependency injection of GemFire managed objects.</para>
<section id="apis:exception-translation">
<title>Exception translation</title>
<para>Using a new data access technology requires not just accommodating
to a new API but also handling exceptions specific to that technology. To
accommodate this case, Spring Framework provides a technology agnostic,
consistent exception <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions">hierarchy</ulink>
that abstracts one from proprietary (and usually checked) exceptions to a
set of focused runtime exceptions. As mentioned in the Spring Framework
documentation, <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">exception
translation</ulink> can be applied transparently to your data access
objects through the use of the <literal>@Repository</literal> annotation
and AOP by defining a PersistenceExceptionTranslationPostProcessor bean.
The same exception translation functionality is enabled when using Gemfire
as long as at least a <classname>CacheFactoryBean</classname> is declared.
The <interfacename>Cache</interfacename> factory acts as an exception
translator which is automatically detected by the Spring infrastructure
and used accordingly.</para>
</section>
<section id="apis:template">
<title><classname>GemfireTemplate</classname></title>
<para>As with many other high-level abstractions provided by the Spring
Framework and related projects, Spring GemFire provides a
<emphasis>template</emphasis> that plays a central role when working with
the GemFire API. The class provides several <emphasis>one-liner</emphasis>
methods, for popular operations but also the ability to
<emphasis>execute</emphasis> code against the native GemFire API without
having to deal with exceptions for example through the
<interfacename>GemfireCallback</interfacename>.</para>
<para>The template class requires a GemFire
<interfacename>Region</interfacename> instance and once configured is
thread-safe and should be reused across multiple classes:</para>
<programlisting language="xml"><bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/></programlisting>
<para>Once the template is configured, one can use it alongside
<interfacename>GemfireCallback</interfacename> to work directly with the
GemFire <interfacename>Region</interfacename>, without having to deal with
checked exceptions, threading or resource management concerns:</para>
<programlisting language="java">template.execute(new GemfireCallback<Iterable<String>>() {
public Iterable<String> doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region<String, String> region = reg;
region.put("1", "one");
region.put("3", "three");
return region.query("length < 5");
}
});</programlisting>
<para>For accessing the full power of the GemFire query language, one can use the <methodname>find</methodname> and <methodname>findUnique</methodname> which, as oppose to the
<methodname>query</methodname> method, can execute queries inside across multiple regions, execute projections just to name a few features. <methodname>find</methodname> method should be
used when the query selects multiple items (through <literal>SelectResults</literal>) and the latter, <methodname>findUnique</methodname>, as the name suggests when only one object is returned.
</para>
</section>
<section id="apis:spring-cache-abstraction">
<title>Support for Spring Cache Abstraction</title>
<para>Since 1.1, Spring GemFire provides an implementation for Spring 3.1
<ulink url="http://static.springsource.org/spring/docs/3.1.0.M2/spring-framework-reference/html/cache.html">cache abstraction</ulink> through the
<literal>org.springframework.data.gemfire.support</literal> package. To use GemFire
as a backing implementation, simply add <literal>GemfireCacheManager</literal> to your configuration:</para>
<programlisting language="xml"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cache="http://www.springframework.org/schema/cache"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
<!-- turn on declarative caching -->
<cache:annotation-driven />
<gfe:cache id="gemfire-cache" />
<!-- declare GemFire Cache Manager -->
<bean id="cacheManager" class="org.springframework.data.gemfire.support.GemfireCacheManager" p:cache-ref="gemfire-cache">
</beans>]]>
</programlisting>
</section>
<section id="apis:tx-mgmt">
<title>Transaction Management</title>
<para>One of the most popular features of Spring Framework is <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html">transaction</ulink>
management. If you are not familiar with it, we strongly recommend <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html#transaction-motivation">looking</ulink>
into it as it offers a consistent programming model that works
transparently across multiple APIs that can be configured either
programmatically or declaratively (the most popular choice).</para>
<para>For GemFire, SGF provides a dedicated, per-cache, transaction
manager that once declared, allows actions on the
<interfacename>Region</interfacename>s to be grouped and executed
atomically through Spring:</para>
<programlisting language="xml"><gfe:transaction-manager id="tx-manager" cache-ref="cache"/></programlisting>
<note>The example above can be simplified even more by eliminating the <literal>cache-ref</literal> attribute if the GemFire cache is defined under the default
name <literal>gemfire-cache</literal>. As with the other SGF namespace elements, if the cache name is not configured, the aforementioned naming convention will used.
Additionally, the transaction manager name, if not specified is <literal>gemfire-transaction-manager</literal>.</note>
<para>or if you prefer <literal>bean</literal> declarations:</para>
<programlisting language="xml"><bean id="tx-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/></programlisting>
<para>Note that currently GemFire supports optimistic transactions with
<emphasis>read committed</emphasis> isolation. Furthermore, to guarantee
this isolation, developers should avoid making
<emphasis>in-place</emphasis> changes, that is manually modifying the
values present in the cache. To prevent this from happening, the
transaction manager configured the cache to use <emphasis>copy on
read</emphasis> semantics, meaning a clone of the actual value is created,
each time a read is performed. This behaviour can be disabled if needed
through the <literal>copyOnRead</literal> property. For more information
on the semantics of the underlying GemFire transaction manager, see the
GemFire <ulink
url="http://www.gemstone.com/docs/6.0.1/product/docs/japi/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.</para>
</section>
<xi:include href="cq-container.xml"/>
<section id="apis:declarable">
<title>Wiring <interfacename>Declarable</interfacename> components</title>
<para>GemFire XML configuration (usually named
<literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to
be declared as part of the fabric configuration. Usually these objects are
<interfacename>CacheLoader</interfacename>s or other pluggable components
into GemFire. Out of the box in GemFire, each such type declared through
XML must implement the <interfacename>Declarable</interfacename> interface
which allows arbitrary parameters to be passed to the declared class
through a <classname>Properties</classname> instance.</para>
<para>In this section we describe how you can configure the pluggable
components defined in <literal>cache.xml</literal> using Spring while
keeping your Cache/Region configuration defined in
<literal>cache.xml</literal> This allows your pluggable components to
focus on the application logic and not the location or creation of
DataSources or other collaboration object.</para>
<para>However, if you are starting on a green-field project, it is
recommended that you configure Cache, Region, and other pluggable
components directly in Spring. This avoids inheriting from the
<interfacename>Declarable</interfacename> interface or the base class
presented in this section. See the following sidebar for more information
on this approach.</para>
<sidebar>
<title>Eliminate <interfacename>Declarable</interfacename>
components</title>
<para>One can configure custom types entirely inside through Spring as
mentioned in <xref linkend="bootstrap:region" />. That way, one does not
have to implement the <interfacename>Declarable</interfacename>
interface and gets access to all the features of the Spring IoC
container (including not just dependency injection but also life-cycle
and instance management).</para>
</sidebar>
<para>As an example of configuring a
<interfacename>Declarable</interfacename> component using Spring, consider
the following declaration (taken from the
<interfacename>Declarable</interfacename> javadoc):</para>
<programlisting language="xml"><cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<parameter name="URL">
<string>jdbc://12.34.56.78/mydb</string>
</parameter>
</cache-loader></programlisting>
<para>To simplify the task of parsing, converting the parameters and
initializing the object, SGF offers a base class
(<classname>WiringDeclarableSupport</classname>) that allows GemFire user
objects to be wired through a <emphasis>template</emphasis> bean
definition or, in case that is missing perform autowiring through the
Spring container. To take advantage of this feature, the user objects need
to extend <classname>WiringDeclarableSupport</classname> which
automatically locates the declaring
<interfacename>BeanFactory</interfacename> and performs wiring as part of
the initialization process.</para>
<sidebar>
<title>Why is a base class needed?</title>
<para>In the current GemFire release there is no concept of an
<emphasis>object factory</emphasis> and the types declared are
instantiated and used as is - that is there are no other ways in which
third parties can take care of the object creation outside GemFire.
Support for this feature is planned for the up-coming GemFire release
(6.5)</para>
</sidebar>
<section id="apis:declarable:template-wiring">
<title>Configuration using <emphasis>template</emphasis>
definitions</title>
<para>When used <classname>WiringDeclarableSupport</classname> tries to
first locate an existing bean definition and use that as wiring
template. Unless specified, the component class name will be used as an
implicit bean definition name. Let's see how our
<classname>DBLoader</classname> declaration would look in that
case:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
private DataSource dataSource;
public void setDataSource(DataSource ds){
this.dataSource = ds;
}
public Object load(LoaderHelper helper) { ... }
}</programlisting>
<programlisting language="xml"><cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no parameter is passed (use the bean implicit name
that is the class name) -->
</cache-loader></programlisting>
<programlisting language="xml"><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="dataSource" ... />
<!-- template bean definition -->
<bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/>
</beans></programlisting>
<para>In the scenario above, as no parameter was specified, a bean with
id/name <literal>com.company.app.DBLoader</literal> was searched for.
The found bean definition is used as a template for wiring the instance
created by GemFire. For cases where the bean name uses a different
convention, one can pass in the <literal>bean-name</literal> parameter
in the GemFire configuration:</para>
<programlisting language="xml"><cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- pass the bean definition template name
as parameter -->
<parameter name="bean-name">
<string>template-bean</string>
</parameter>
</cache-loader></programlisting>
<programlisting language="xml"><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="dataSource" ... />
<!-- template bean definition -->
<bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/>
</beans></programlisting>
<note>
<para>The <emphasis>template</emphasis> bean definitions do not have
to be declared in XML - any format is allowed (Groovy, annotations,
etc..).</para>
</note>
</section>
<section id="apis:declarable:autowiring">
<title>Configuration using auto-wiring and annotations</title>
<para>If no bean definition is found, by default,
<classname>WiringDeclarableSupport</classname> will <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-autowire">autowire</ulink>
the declaring instance. This means that unless any dependency injection
<emphasis>metadata</emphasis> is offered by the instance, the container
will find the object setters and try to automatically satisfy these
dependencies. However, one can also use JDK 5 annotations to provide
additional information to the auto-wiring process. We strongly recommend
reading the dedicated <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">chapter</ulink>
in the Spring documentation for more information on the supported
annotations and enabling factors.</para>
<para>For example, the hypothetical <literal>DBLoader</literal>
declaration above can be injected with a Spring-configured
<interface>DataSource</interface> in the following way:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
// use annotations to 'mark' the needed dependencies
@javax.inject.Inject
private DataSource dataSource;
public Object load(LoaderHelper helper) { ... }
}</programlisting>
<programlisting language="xml"><cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no need to declare any parameters anymore
since the class is auto-wired -->
</cache-loader></programlisting>
<programlisting language="xml"><?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<!-- enable annotation processing -->
<context:annotation-config/>
</beans></programlisting>
<para>By using the JSR-330 annotations, the cache loader code has been
simplified since the location and creation of the DataSource has been
externalized and the user code is concerned only with the loading
process. The <interfacename>DataSource</interfacename> might be
transactional, created lazily, shared between multiple objects or
retrieved from JNDI - these aspects can be easily configured and changed
through the Spring container without touching the
<classname>DBLoader</classname> code.</para>
</section>
</section>
</chapter>