Skip to content

Commit

Permalink
Merge branch 'master' of github.com:teiid/teiid-documents
Browse files Browse the repository at this point in the history
  • Loading branch information
@shawkins
shawkins committed Sep 26, 2016
2 parents c4650b6 + 6c3dd5b commit c5b2bf5
Show file tree
Hide file tree
Showing 2 changed files with 103 additions and 110 deletions.
149 changes: 102 additions & 47 deletions admin/Infinispan_HotRod_Data_Sources.adoc
View file
@@ -1,61 +1,107 @@

= Infinispan HotRod Data Sources

Infinispan HotRod data sources use a Teiid specific JCA connector that is deployed into {{ book.asVersionNumber }} during installation. This connector can be configured to support the following modes of Infinispan caches that will be accessed using the Hot Rod client:
Infinispan caches running in client/server mode can use a Teiid specific JCA connector for accessing as a data source, which is deployed into {{ book.asVersionNumber }} during installation. This connector can be configured to support the accessing of a remote Infinispan cache using the the Hot Rod client.

|===
|Cache Type |Property Name |Obtain Cache By

|Remote Cache
|CacheJndiName
|using JNDI

|Remote Cache
|RemoteServerList
|Server list, specify 1 or more host:port’s
Each Infinispan cache that has a referenced pojo object by doing a "get(key)" on the cache, for which you want to access, will require a different configured resource-adapter.

|Remote Cache
|HotRodClientPropertiesFile
|HotRod client properties file
|===
There are two options for how the Infinispan schema can be configured in the connector; protobuf annotations or protobuf (.proto) file with marshaller(s). The following are the requirements.

== *Requirement*

* (option 1) Minimum, JDG 6.2 - this requires you provide a protobuf definition file and pojo marsharller for the pojo to be cached
* (option 2) Minimum, JDG 6.6 - this can be used when the pojo has protobuf annotations which trigger the creation of the protobuf definition and pojo marshaller by JDG.
* (option 1) Minimum, JDG 6.2 - this requires you provide a protobuf definition file and pojo marshaller(s) for the pojo to configure the JDG schema
* (option 2) Minimum, JDG 6.6 - this can be used when the pojo has defined protobuf annotations which are used to configure the JDG schema.

See link:../reference/Infinispan_HotRod_Translator.adoc[Infinispan HotRod Translator] for details on how the the metadata will be exposed or can be manually configured based on the schema that's defined for this data source.


== *Configuration*

The following property is required as it provides the mapping to the Infinispan cache and pojo that will be accessed.

=== *Pojo Jar*
|===
|Property Name |Property Template|Description

The pojo class is the object that will be used to store the data in the cache. It should be built accordingly:
| CacheTypeMap |cacheName:className[;pkFieldName[:cacheKeyJavaType]] | For the indicated cacheName, map the root Java Object (pojo) class name. Optionally, but required for updates, identify which class attribute is the primary key to the cache. Optionally, identify primary key java type when different than class attribute type
|===

* To take advantage of the cache being indexed enabled, should annotate the class. See JDG Protobuf Annotations at https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf
* The class should be packaged into a jar so that it can be deployed as a module
=== *Protobuf Definition and Marshaller(s)*

The following properties are required when the protobuf definition file (.proto) and the pojo marshaller(s) are being used to configure the JDG schema:

To configure the use of the pojo, do the following:
|===
|Property Name |Req. |Property Template|Description

* Deploy the pojo jar as a module in the jboss-as server. Then define the "lib" property in the -vdb.xml and assign the correct module name. This can be done using the following template:
[source,xml]
| ProtobufDefinitionFile | Y | | Path to the Google Protobuf file that's packaged in a jar (ex: /quickstart/addressbook.proto)
| MessageMarshallers | Y | marshaller \[,marshaller,..\] | Contains Class names mapped its respective message marshaller, (class:marshaller,\[class:marshaller,..\]), that are to be registered for serialization
| MessageDescriptor | Y | | Message descriptor class name for the root object in cache
|===

=== *Pojo Class/Jar*

The pojo class is the object that is used to store the data in the cache. It should be built accordingly:

* If the pojo is to be used to define the schema, then should use the protobuf annotations. See JDG Protobuf Annotations at https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf
* If the protobuf definition and mashaller(s) are to be used, then these should also be packaged in the jar (or a separate jar that is included in the classpath).
* The class should be packaged into a jar so that it can be deployed as a module.

[source,java]
.*Sample Pojo with Annotations*
----
<property name ="lib" value ="{pojo_module_name}"></property>
public class Person {
@ProtoField(number = 2, required = true)
public String name;
@ProtoField(number = 1, required = true)
public int id;
@ProtoField(number = 3)
public String email;
private List<PhoneNumber> phones;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public List<PhoneNumber> getPhones() {
return phones;
}
public void setPhones(List<PhoneNumber> phones) {
this.phones = phones;
}
}
----


=== *Reading and Writing to the Cache*
To configure the resource-adapter to use the pojo, do the following:

The following are the required properties:
* Deploy the pojo jar as a module in the jboss-as server.

|===
|Property Name |Property Template|Description

| CacheTypeMap |cacheName:className[;pkFieldName[:cacheKeyJavaType]] | For the indicated cache, map the root Java Object class name. Optionally, but required for updates, identify which class attribute is the primary key to the cache. Identify primary key java type when different than class attribute type
|===
=== *Reading and Writing to the Cache*

The following are the property options for defining how the RemoteCacheManager will be created/accessed:

One of the following properties is required for defining how the RemoteCacheManager will be created/accessed:

|===
|Property Name |Req. |Property Template|Description
Expand All @@ -65,17 +111,8 @@ The following are the property options for defining how the RemoteCacheManager w
| HotRodClientPropertiesFile | N | | The HotRod properties file for configuring a connection to a remote cache
|===

The following properties are required when the pojo is not annotated:

|===
|Property Name |Req. |Property Template|Description

| ProtobinFile | Y | | Path to the Google Protobin file that's packaged in a jar (ex: /quickstart/addressbook.protobin)
| MessageMarshallers | Y | marshaller \[,marshaller,..\] | Contains Class names mapped its respective message marshaller, (class:marshaller,\[class:marshaller,..\]), that are to be registered for serialization
| MessageDescriptor | Y | | Message descriptor class name for the root object in cache
|===

The following are optional properties:
The following property should be defined when using protobuf definition file and marshallers:

|===
|Property Name |Req. |Property Template|Description
Expand All @@ -86,13 +123,14 @@ The following are optional properties:


=== *Using Remote Cache for External Materialization*

The following are the additional properties that need to be configured if using the Remote Cache for external materialization:

|===
|Property Name |Req. |Description

| StagingCacheName | Y | Cache name for the staging cache used in materialization
| AliasCacheName | Y | Cache name for the alias cache used in tracking aliasing of the caches used in materialization
| AliasCacheName | Y | Cache name for the alias cache used in tracking aliasing of the caches used in materialization. This cache can be shared with other configured materializations.
|===


Expand All @@ -102,7 +140,7 @@ The following are the additional properties that need to be configured if using
There are many ways to create the data source, using CLI, link:AdminShell.adoc[AdminShell], admin-console etc. The first example is an xml snippet of a resource-adapter that is used to connect to the JDG remote-query quick start:me

[source,xml]
.*Sample Resource Adapter*
.*Sample Resource Adapter defining Protobuf Definition and Marshaller*
----
<resource-adapter id="infinispanRemQS">
<module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>
Expand All @@ -111,8 +149,8 @@ There are many ways to create the data source, using CLI, link:AdminShell.adoc[A
<config-property name="CacheTypeMap">
addressbook:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id
</config-property>
<config-property name="ProtobinFile">
/quickstart/addressbook.protobin
<config-property name="ProtobufDefinitionFile">
/quickstart/addressbook.proto
</config-property>
<config-property name="MessageDescriptor">
quickstart.Person
Expand All @@ -130,10 +168,27 @@ There are many ways to create the data source, using CLI, link:AdminShell.adoc[A
</resource-adapter>
----

[source,xml]
.*Sample Resource Adapter using Pojo with annotations*
----
<resource-adapter id="infinispanRemQSDSL">
<module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.dsl"/>
<connection-definitions>
<connection-definition class-name="org.teiid.resource.adapter.infinispan.dsl.InfinispanManagedConnectionFactory" jndi-name="java:/infinispanRemoteDSL" enabled="true" use-java-context="true" pool-name="infinispanRemoteDSL">
<config-property name="RemoteServerList">
127.0.0.1:11322
</config-property>
<config-property name="CacheTypeMap">
addressbook_indexed:org.jboss.as.quickstarts.datagrid.hotrod.query.domain.Person;id
</config-property>
</connection-definition>
</connection-definitions>
</resource-adapter>
----

The following is an example when configured for external materialization:

[source,xml]
.*Sample Resource Adapter for external materialization*
----
<resource-adapter id="infinispanRemQSDSL">
<module slot="main" id="org.jboss.teiid.resource-adapter.infinispan.hotrod"/>
Expand Down
64 changes: 1 addition & 63 deletions reference/Infinispan_HotRod_Translator.adoc
View file
Expand Up @@ -18,7 +18,7 @@ If you are using JDG in library mode, see the link:Infinispan_LibMode_Translator
The following are the connector capabilities:

* Compare Criteria - EQ
* Compare Criteria Ordered - LT, GT, LE, GE - if the supportsCompareCriteriaOrdered translator override is set to true. It defaults to false due to an https://issues.jboss.org/browse/TEIID-3627[issue with JDG].
* Compare Criteria Ordered - LT, GT, LE, GE - support for SupportsComapareCriteriaOrdered will be controlled by the version of JDG being accessed. Any JDG version 6.5 and prior will have this set to false due to an https://issues.jboss.org/browse/TEIID-3627[issue with JDG].
* And/Or Criteria
* In Criteria
* Like Criteria
Expand Down Expand Up @@ -51,68 +51,6 @@ To be done:
The *ispn-hotrod* translator is not configured, out-of-the-box, in the standalone-teiid.xml configuration. To configure the translator, run the https://github.com/teiid/teiid/blob/master/build/kits/jboss-as7/docs/teiid/datasources/infinispan/add-infinispan-hotrod-translator.cli[add-infinispan-hotrod-translator.cli] script. This script can also be found in the teiid-jboss-dist.zip kit, under docs/teiid/datasources/infinispan. See the https://docs.jboss.org/author/display/teiidexamples/JBoss+Data+Grid+Remote+Cache+as+a+Data+Source[jdg-remote-cache] quick start for an example. Note, this assumes you will be installing a separate JDG server, which will be accessed via the Hot Rod Client installed into the Teiid server.


=== Configuring Pojo class
The pojo class is the object that will be used to store the data in the cache. It should be built accordingly:

* To take advantage of the cache being indexed enabled, should annotate the class. See JDG Indexing With Protobuf Annotations at https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html-single/Infinispan_Query_Guide/index.html#Custom_Fields_Indexing_with_Protobuf
* The class should be packaged into a jar so that it can be deployed as a module

Example class:
[source,java]
----
public class Person {
@ProtoField(number = 2, required = true)
public String name;
@ProtoField(number = 1, required = true)
public int id;
@ProtoField(number = 3)
public String email;
private List<PhoneNumber> phones;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public List<PhoneNumber> getPhones() {
return phones;
}
public void setPhones(List<PhoneNumber> phones) {
this.phones = phones;
}
}
----

To configure the use of the pojo, do the following:

* Deploy the pojo jar as a module in the jboss-as server. Then define the "lib" property in the -vdb.xml and assign the correct module name. This can be done using the following template:
[source,xml]
----
<property name ="lib" value ="{pojo_module_name}"></property>
----


== *Metadata*

=== *Options for Defining*
Expand Down

0 comments on commit c5b2bf5

Please sign in to comment.