Fichier XML du descripteur d'ObjectGrid

Pour configurer WebSphere eXtreme Scale, utilisez un fichier XML de descripteur d'ObjectGrid et l'API ObjectGrid.

Dans les sections ci-après, des exemples de fichier XML sont fournis pour illustrer les diverses configurations. Chaque élément et attribut du fichier XML est défini. Utilisez le schéma du XML du descripteur d'ObjectGrid pour créer le fichier XML du descripteur. Pour un exemple de schéma XML de descripteur, voir Fichier objectGrid.xsd.

Une version modifiée du fichier companyGrid.xml d'origine est utilisée. Le fichier companyGridSingleMap.xml ci-après ressemble au fichier companyGrid.xml. Le fichier companyGridSingleMap.xml contient une mappe et le fichier companyGrid.xml en contient quatre. Les éléments et attributs du fichier sont décrits en détails après l'exemple.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
		xmlns="http://ibm.com/ws/objectgrid/config">

		<objectGrids>
				<objectGrid name="CompanyGrid">
						<backingMap name="Customer"/>
				</objectGrid>
		</objectGrids>
</objectGridConfig>

Elément objectGridConfig

L'élément objectGridConfig correspond à l'élément de niveau supérieur du fichier XML. Enregistrez cet élément dans votre document XML eXtreme Scale, comme illustré dans l'exemple précédent. Cet élément configure l'espace de noms du fichier et l'emplacement du schéma. Le schéma est défini dans le fichier objectGrid.xsd.

Elément objectGrids

L'élément objectGrids sert de conteneur à tous les éléments objectGrid. Dans le fichier companyGridSingleMap.xml, l'élément objectGrids contient un objectGrid, l'objectGrid CompanyGrid.

Elément objectGrid

Utilisez l'élément objectGrid pour définir un ObjectGrid. Chacun des attributs de l'élément objectGrid correspond à une méthode dans l'interface ObjectGrid.
Attributs
name
Indique le nom affecté à l'ObjectGrid. La validation XML échoue si cet attribut est manquant. (Obligatoire)
securityEnabled
Active la sécurité au niveau ObjectGrid, qui active les autorisations d'accès aux données de la mappe, lorsque vous affectez à l'attribut la valeur true. La valeur par défaut est true. (facultatif).
authorizationMechanism
Définit le mécanisme d'autorisation de l'élément. Vous pouvez affecter à cet attribut une ou plusieurs valeurs : AUTHORIZATION_MECHANISM_JAAS ou AUTHORIZATION_MECHANISM_CUSTOM. La valeur par défaut est AUTHORIZATION_MECHANISM_JAAS. Vous devez définir l'attribut securityEnabled avec la valeur true pour que l'attribut authorizationMechanism soit appliqué. (facultatif).
permissionCheckPeriod
Spécifie un nombre entier de secondes qui indique la fréquence de vérification des droits d'accès utilisés pour autoriser l'accès d'un client. La valeur par défaut est 0. Si vous affectez à l'attribut la valeur 0, chaque appel de méthode get, put, update, remove ou evict demande au mécanisme d'autorisation, une autorisation JAAS (Java Authentication and Authorization Service) ou une autorisation personnalisée, de vérifier si le sujet actuel possède les droits requis. Une valeur supérieure à 0 indique le nombre de secondes pendant lequel un ensemble de droits d'accès doit être placé en cache avant de retourner au mécanisme d'autorisation pour être régénéré. Vous devez définir l'attribut securityEnabled avec la valeur true pour que l'attribut permissionCheckPeriod soit appliqué. (facultatif).
txTimeout
Indique le délai d'exécution maximal autorisé pour une transaction. Si une transaction n'est pas terminée dans ce laps de temps, la transaction est marquée pour annulation et une exception TransactionTimeoutException est générée. Si vous attribuez la valeur 0, le paramètre par défaut 10 minutes est utilisé comme délai d'expiration de transactions. (Facultatif).
entityMetadataXMLFile
Indique le chemin d'accès au fichier descripteur XML d'entité qui définit le schéma d'entité. Définissez les entités avant de démarrer le serveur de catalogue afin que chaque entité puisse être associée à une mappe de sauvegarde.
  • Pour un répertoire relatif : indiquez l'emplacement relatif à l'emplacement du fichier objectgrid.xml.
  • Pour un chemin d'accès absolu : indiquez l'emplacement à l'aide d'une URL, telle que file:// ou http://.
(Facultatif).
<objectGrid
(1)	name="objectGridName"
(2)	securityEnabled="true" | "false"
(3)	authorizationMechanism="AUTHORIZATION_MECHANISM_JASS" | "AUTHORIZATION_MECHANISM_CUSTOM"
(4) 	permissionCheckPeriod="permission_check_period"
(5)	txTimeout="seconds"
(6)	entityMetadataXMLFile="URL"
/>
Dans l'exemple ci-après, le fichier companyGridObjectGridAttr.xml illustre une manière de configurer les attributs d'un élément objectGrid. La sécurité est activée, le mécanisme d'autorisation est JAAS et la période de vérification des droits d'accès est de 45 secondes. Le fichier enregistre également les entités en spécifiant un attribut entityMetadataXMLFile.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlnc:xsi="http:www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid" securityEnabled="true"
			authorizationMechanism="AUTHORIZATION_MECHANISM_JASS"
			permissionCheckPeriod="45"
			entityMetadataXMLFile="companyGridEntities.xml">
			<backingMap name="Customer"/>
		</objectGrid>
	</objectGrids>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridObjectGridAttr.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

companyGrid.setSecurityEnabled();
companyGrid.setAuthorizationMechanism(SecurityConstants.AUTHORIZATION_MECHANISM_JAAS);
companyGrid.setPermissionCheckPeriod(45);
companyGrid.registerEntities(new URL("file:companyGridEntities.xml"));

Elément backingMap

L'élément backingMap est utilisé pour définir une instance BackingMap sur un ObjectGrid. Chacun des attributs de l'élément backingMap correspond à une méthode de l'interface BackingMap. Pour plus d'informations, voir les Interface BackingMap.
Attributs
name
Indique le nom attribué à l'instance backingMap. Si cet attribut est manquant, la validation XML échoue. (Obligatoire)
readOnly
Définit une instance BackingMap en lecture/écriture lorsque vous spécifiez l'attribut avec la valeur false. Si vous affectez à l'attribut la valeur true, l'instance BackingMap est en lecture seule. (facultatif).
template
Indique si des mappes dynamiques peuvent être utilisées. Spécifiez true si la mappe BackingMap est un modèle de mappe. Les modèles de mappe peuvent être utilisés pour créer dynamiquement des mappes après le démarrage d'ObjectGrid. Les appels à Session.getMap(String) entraînent la création de mappes dynamiques si le nom transmis à la méthode correspond à l'expression régulière spécifiée dans l'attribut name de la mappe de sauvegarde. La valeur par défaut est false. (facultatif).
pluginCollectionRef
Indique une référence à un plug-in backingMapPluginCollection. La valeur de cet attribut doit correspondre à l'attribut ID d'un plug-in backingMapCollection. La validation échoue s'il n'existe aucun ID correspondant. Définissez l'attribut pour réutiliser les plug-in BackingMap. (Facultatif).
numberOfBuckets
Indique le nombre de compartiments à utiliser par l'instance BackingMap. L'instance BackingMap utilise une mappe de hachage pour l'implémentation. S'il existe plusieurs entrées dans la mappe de sauvegarde, plus les compartiments sont nombreux, plus les performances sont meilleures car le risque de collision diminue lorsque le nombre de compartiments augmente. Plus les compartiments sont nombreux, plus les accès simultanés le sont également. Spécifiez la valeur 0 pour désactiver le cache local sur un client lors de la communication à distance avec eXtreme Scale. Lorsque vous définissez la valeur 0 pour un client, définissez la valeur dans le fichier descripteur XML ObjectGrid de remplacement client uniquement. (facultatif).
preloadMode
Définit le mode de préchargement si un plug-in de programme de chargement est défini pour cette instance BackingMap. La valeur par défaut est false. Si l'attribut possède la valeur true, la méthode Loader.preloadMap(Session, BackingMap) est appelée de manière asynchrone. Sinon, l'exécution de la méthode est bloquée lors du chargement des données pour que le cache ne soit pas disponible avant la fin du préchargement. Le préchargement a lieu au cours de l'initialisation. (facultatif).
lockStrategy
Indique si le gestionnaire de verrouillage interne est utilisé chaque fois qu'une transaction accède à une entrée de mappe. Spécifiez l'une des trois valeurs suivantes pour cet attribut : OPTIMISTIC, PESSIMISTIC ou NONE. La valeur par défaut est OPTIMISTIC. (facultatif).

La stratégie de verrouillage optimiste est généralement utilisée lorsqu'une mappe ne possède pas de plug-in Loader, qu'elle est la plupart du temps lue, mais rarement éditée ou mise à jour et que le verrouillage n'est pas fourni par le gestionnaire de persistance avec l'utilisation d'eXtreme Scale comme cache secondaire ou par l'application. Un verrou exclusif est obtenu sur une entrée de mappe insérée, mise à jour ou supprimée lors de la phase de validation. Le verrou garantit que les informations de version ne peuvent pas être modifiées par une autre transaction alors que la transaction en cours de validation effectue une vérification de version optimiste.

La stratégie de verrouillage pessimiste est généralement utilisée pour une mappe qui ne possède pas de plug-in Loader, quand le verrouillage n'est pas assuré par un gestionnaire de persistance avec l'utilisation d'eXtreme Scale comme cache secondaire, par un plug-in Loader ou par l'application. La stratégie de verrouillage pessimiste est utilisée en cas d'échecs trop fréquents de la stratégie de verrouillage optimiste car les transactions de mise à jour entrent souvent en collision sur la même entrée de mappe.

La stratégie sans verrouillage indique que le gestionnaire de verrouillage interne n'est pas requis. Le contrôle des accès simultanés est fourni en dehors d'eXtreme Scale, par le gestionnaire de persistance qui utilise eXtreme Scale comme application ou cache secondaire ou par le plug-in du chargeur qui utilise les verrous de base de données pour contrôler les accès simultanés.

Pour plus d'informations, voir Gestionnaire de verrous.

numberOfLockBuckets
Définit le nombre de compartiments de verrouillage utilisés par le gestionnaire de verrouillage pour l'instance BackingMap. Affectez à l'attribut lockStrategy la valeur OPTIMISTIC ou PESSIMISTIC afin de créer un gestionnaire de verrouillage pour l'instance BackingMap. Le gestionnaire de verrouillage utilise une mappe de hachage pour rechercher les entrées verrouillées par une ou plusieurs transactions. S'il existe de nombreuses entrées, plus les compartiments de verrouillage sont nombreux, plus les performances sont meilleures car le risque de collision diminue lorsque le nombre de compartiments augmente. Plus les compartiments de verrouillage sont nombreux, plus les accès simultanés le sont également. Affectez à l'attribut lockStrategy la valeur NONE pour indiquer à l'instance BackingMap de ne pas utiliser de gestionnaire de verrouillage. (Facultatif).
lockTimeout
Définit le délai de verrouillage utilisé par le gestionnaire de verrouillage pour l'instance BackingMap. Affectez à l'attribut lockStrategy la valeur OPTIMISTIC ou PESSIMISTIC afin de créer un gestionnaire de verrouillage pour l'instance BackingMap. Pour empêcher les interblocages, le gestionnaire de verrouillage possède un délai d'expiration par défaut de 15 secondes. Si le délai d'expiration est dépassé, une exception LockTimeoutException est générée. La valeur par défaut de 15 secondes suffit pour la plupart des applications, mais sur un système particulièrement chargé, le délai d'expiration peut être dépassé en l'absence d'interblocage. Utilisez l'attribut lockTimeout pour spécifier une valeur supérieure à la valeur par défaut afin d'empêcher les fausses exceptions de délai d'expiration dépassé. Affectez à l'attribut lockStrategy la valeur NONE pour indiquer à l'instance BackingMap de ne pas utiliser de gestionnaire de verrouillage. (facultatif).
CopyMode
Indique si une opération get d'une entrée de l'instance BackingMap renvoie la valeur réelle, une copie de la valeur ou un proxy de la valeur. Affectez à l'attribut CopyMode l'une des cinq valeurs suivantes :
COPY_ON_READ_AND_COMMIT
La valeur par défaut est COPY_ON_READ_AND_COMMIT. Spécifiez la valeur COPY_ON_READ_AND_COMMIT pour qu'une application ne fasse jamais référence à l'objet de valeur qui se trouve dans l'instance BackingMap. A la place, l'application utilise toujours une copie de la valeur qui se trouve dans l'instance BackingMap. (facultatif).
COPY_ON_READ
Spécifiez la valeur COPY_ON_READ pour améliorer les performances par rapport à la valeur COPY_ON_READ_AND_COMMIT en éliminant la copie créée lors de la validation d'une transaction. Pour conserver l'intégrité des données de la mappe de sauvegarde, l'application s'engage à supprimer toutes les références à une entrée une fois que la transaction est validée. Si vous définissez cette valeur, une méthode ObjectMap.get renvoie une copie de la valeur au lieu d'une référence à la valeur, ce qui garantit que les modifications apportées par l'application à la valeur n'affectent pas l'élément BackingMap tant que la transaction n'est pas validée.
COPY_ON_WRITE
Spécifiez la valeur COPY_ON_WRITE pour améliorer les performances par rapport à la valeur COPY_ON_READ_AND_COMMIT en éliminant la copie créée lors du premier appel de la méthode ObjectMap.get par une transaction pour une clé donnée. A la place, la méthode ObjectMap.get renvoie un proxy de la valeur au lieu d'une référence directe à l'objet de valeur. Le proxy garantit qu'aucune copie de la valeur n'est effectuée tant que l'application n'appelle pas de méthode set sur l'interface de la valeur.
NO_COPY
Spécifiez la valeur NO_COPY pour permettre à une application de ne jamais modifier d'objet de valeur obtenu à l'aide d'une méthode ObjectMap.get en échange de meilleures performances. Spécifiez la valeur NO_COPY pour les mappes associées aux entités de l'API EntityManager.
COPY_TO_BYTES
Spécifiez la valeur COPY_TO_BYTES pour améliorer l'encombrement mémoire des objets de type complexe et les performances lorsque la copie d'un objet s'appuie sur la sérialisation. Si un objet ne peut pas être cloné ou qu'aucune interface ObjectTransformer personnalisée avec une méthode copyValue efficace n'est fournie, le mécanisme de copie par défaut doit sérialiser et inflatez l'objet pour effectuer une copie. Avec le paramètre COPY_TO_BYTES, l'inflation n'est effectuée que lors d'une opération de lecture et la sérialisation, lors d'une validation.
Pour plus d'informations sur ces paramètres, voir les Optimisation du mode de copie.
valueInterfaceClassName
Indique une classe requise lorsque vous affectez à l'attribut CopyMode la valeur COPY_ON_WRITE. Cet attribut est ignoré pour tous les autres modes. La valeur COPY_ON_WRITE utilise un proxy lors des appels de méthode ObjectMap.get. Le proxy garantit qu'aucune copie de la valeur n'est effectuée tant que l'application n'appelle pas de méthode set dans la classe définie comme attribut valueInterfaceClassName. (Facultatif).
copyKey
Indique si la copie de la clé est requise lors de la création d'une entrée de mappe. La copie de l'objet de clé permet à l'application d'utiliser le même objet de clé pour chaque opération ObjectMap. Spécifiez la valeur true pour copier l'objet de clé lors de la création d'une entrée de mappe. La valeur par défaut est false. (facultatif).
nullValuesSupported
Spécifiez la valeur true pour prendre en charge les valeurs null dans la mappe d'objets. Si les valeurs null sont admises, une opération get qui renvoie la valeur null peut indiquer que la valeur est null ou que la mappe ne contient pas la clé transmise à la méthode. La valeur par défaut est true. (facultatif).
ttlEvictorType
Indique comment est calculée l'heure d'expiration d'une entrée BackingMap. Donnez à cet attribut l'une de ces valeurs : CREATION_TIME, LAST_ACCESS_TIME, LAST_UPDATE_TIME ou NONE. La valeur CREATION_TIME indique que l'heure d'expiration de l'entrée correspond à la somme de l'heure de création de l'entrée et de la valeur de l'attribut timeToLive. La valeur LAST_ACCESS_TIME indique que l'heure d'expiration de l'entrée correspond à la somme de l'heure du dernier accès à l'entrée (que celle-ci ait été modifiée ou simplement lue) et de la valeur de l'attribut timeToLive. La valeur LAST_UPDATE_TIME indique que l'heure d'expiration de l'entrée correspond à la somme de l'heure de la dernière modification de l'entrée et de la valeur de l'attribut timeToLive. La valeur NONE, qui est la valeur par défaut, indique qu'une entrée n'a pas de délai d'expiration et figure dans l'instance BackingMap tant que l'application ne supprime pas ou n'invalide pas explicitement l'entrée. (Facultatif).
timeToLive
Indique en secondes combien de temps chaque entrée de mappe est présente. La valeur par défaut 0 signifie que l'entrée de mappe est présente indéfiniment ou jusqu'à ce que l'application la supprime ou l'invalide de manière explicite. Sinon, l'expulseur TTL expulse l'entrée de mappe en fonction de cette valeur. (Facultatif).
viewRef
Indique que la mappe de sauvegarde est une mappe de vue. (Facultatif).
writeBehind
Indique que l'écriture différée est prise en charge avec les paramètres write-behind (facultatif). Les paramètres write-behind consistent en une durée maximale de mise à jour et un nombre maximal de mises à jour de clés. Leur format est "[T(time)][;][C(count)]". La base de données est mise à jour si l'un des événements suivants se produit :
  • La durée de mise à jour maximale, spécifiée en secondes, est dépassée depuis la dernière mise à jour.
  • Le nombre de mises à jour disponibles dans la mappe de files d'attente a atteint le nombre maximal de mises à jour.

Pour plus d'informations, voir Mise en cache en écriture différée.

La prise en charge de l'écriture différée est une extension du plug-in Loader, qui vous permet d'intégrer eXtreme Scale à la base de données. A ce sujet, vous pouvez consulter avec profit les explications Configuration des chargeurs JPA sur la configuration d'un chargeur JPA.

evictionTriggers
Définit les types de déclencheur d'expulsion supplémentaires à utiliser. Tous les expulseurs de la mappe de sauvegarde utilisent cette liste de déclencheurs supplémentaires. Pour éviter une exception IllegalStateException, cet attribut doit être appelé avant la méthode ObjectGrid.initialize(). En outre, notez que la méthode ObjectGrid.getSession() appelle la méthode ObjectGrid.initialize() de manière implicite si cette dernière doit toujours être appelée par l'application. Les entrées de la liste de déclencheurs sont séparées par des points-virgules. Les déclencheurs d'expulsion Current incluent MEMORY_USAGE_THRESHOLD. (facultatif).
<backingMap
(1)			name="objectGridName"
(2)			readOnly="true" | "false"
(3)			template="true" | "false"
(4)			pluginCollectionRef="reference to backingMapPluginCollection"
(5)			numberOfBuckets="number of buckets"
(6)			preloadMode="true" | "false"
(7)			lockStrategy="OPTIMISTIC" | "PESSIMISTIC" | "NONE"
(8)			numberOfLockBuckets="number of lock buckets"
(9)			lockTimeout="lock timeout"
(10)			copyMode="COPY_ON_READ_AND_COMMIT" | "COPY_ON_READ" | "COPY_ON_WRITE"
							| "NO_COPY" | "COPY_TO_BYTES"
(11)			valueInterfaceClassName="value interface class name"
(12)			copyKey="true" | "false"
(13)			nullValuesSupported="true" | "false"
(14)			ttlEvictorType="CREATION_TIME" | "LAST_ACCESS_TIME" | "LAST_UPDATE_TIME" | NONE"
(15)			timeToLive="time to live"
(16)			streamRef="reference to a stream"
(17)			viewRef="reference to a view"
(18)			writeBehind="write-behind parameters"
(19)			evictionTriggers="MEMORY_USAGE_THRESHOLD"
/>		
Dans l'exemple ci-après, le fichier companyGridBackingMapAttr.xml permet d'illustrer un exemple de configuration de mappe de sauvegarde.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			 <backingMap name="Customer" readOnly="true"
					numberOfBuckets="641" preloadMode="false"
					lockStrategy="OPTIMISTIC" numberOfLockBuckets="409"
					lockTimeout="30" copyMode="COPY_ON_WRITE"
					valueInterfaceClassName="com.ibm.websphere.samples.objectgrid.CounterValueInterface"
					copyKey="true" nullValuesSupported="false"
					ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3000"/>
		</objectGrid>
	</objectGrids>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridBackingMapAttr.xml de l'exemple précédent :
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

BackingMap customerMap = companyGrid.defineMap("Customer");
customerMap.setReadOnly(true);
customerMap.setNumberOfBuckets(641);
customerMap.setPreloadMode(false);
customerMap.setLockStrategy(LockStrategy.OPTIMISTIC);
customerMap.setNumberOfLockBuckets(409);
customerMap.setLockTimeout(30);

// Si vous spécifiez le mode de copie COPY_ON_WRITE, une classe valueInterface est requise
customerMap.setCopyMode(CopyMode.COPY_ON_WRITE, 
	com.ibm.websphere.samples.objectgrid.CounterValueInterface.class);
customerMap.setCopyKey(true);
customerMap.setNullValuesSupported(false);
customerMap.setTtlEvictorType(TTLType.LAST_ACCESS_TIME);
customerMap.setTimeToLive(3000); // spécifie une durée de vie de 50 minutes

Elément bean

Utilisez l'élément bean pour définir des plug-in. Vous pouvez connecter des plug-in à des éléments objectGrid et BackingMap.
Attributs
id
Indique le type de plug-in à créer. (Obligatoire)
Les plug-in valides pour un bean qui est un élément enfant de l'élément objectGrid sont inclus dans la liste suivante :
  • Plug-in TransactionCallback
  • Plug-in ObjectGridEventListener
  • Plug-in SubjectSource
  • Plug-in SubjectValidation
Les plug-in valides pour un bean qui est un élément enfant de l'élément backingMapPluginCollection sont inclus dans la liste suivante :
  • Plug-in Loader
  • Plug-in ObjectTransformer
  • Plug-in OptimisticCallback
  • Plug-in Evictor
  • Plug-in MapEventListener
  • Plug-in MapIndex
className
Spécifie le nom de la classe ou du bean Spring à instancier pour créer le plug-in. La classe doit implémenter l'interface de type plug-in. Par exemple, si vous définissez ObjectGridEventListener comme valeur pour l'attribut id, la valeur d'attribut className doit faire référence à une classe qui implémente l'interface ObjectGridEventListener. className ou osgiService est nécessaire.
osgiService
Définit le nom du service OSGi à rechercher dans le gestionnaire de services OSGi. Dans une infrastructure Eclipse Equinox OSGi avec conteneur Eclipse Gemini ou Apache Aries Blueprint, les plug-in peuvent être définis à l'aide d'un fichier OSGi Blueprint XML. Les autres propriétés de bean ne sont généralement pas utilisées lorsque vous utilisez un nom osgiService, car les propriétés des beans sont définies dans le fichier de configuration Blueprint. Pour plus d'informations, voir Configuration des plug-in OSGi en utilisant le fichier descripteur XML ObjectGrid. className ou osgiService est nécessaire.
<bean
(1)	id="TransactionCallback" | "ObjectGridEventListener" |"SubjectSource" |
     "SubjectValidation" | "Loader" | "ObjectTransformer" |
    "OptimisticCallback" | "Evictor" | "MapEventListener" | "MapIndexPlugin"
(2)	className="class name" | "(spring)bean name"
/>

Dans l'exemple ci-après, le fichier companyGridBean.xml permet d'illustrer la manière de configurer des plug-in à l'aide de l'élément bean. Un plug-in ObjectGridEventListener est ajouté à l'ObjectGrid CompanyGrid. L'attribut className de ce bean est la classe com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener. Cette classe implémente l'interface com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener, si nécessaire.

Un plug-in BackingMap est également défini dans le fichier companyGridBean.xml. Un plug-in d'expulseur est ajouté à l'instance de mappe de sauvegarde Customer. L'ID bean étant Evictor, l'attribut className doit spécifier une classe qui implémente l'interface com.ibm.websphere.objectgrid.plugins.Evictor. La classe com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor implémente cette interface. La mappe de sauvegarde référence ses plug-in à l'aide de l'attribut pluginCollectionRef.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			bean id="ObjectGridEventListener"
				className="com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener"/>
			<backingMap name="Customer"
				pluginCollectionRef="customerPlugins"/>
		</objectGrid>
	</objectGrids>
	<backingMapPluginCollections>
		<backingMapPluginCollection id="customerPlugins">
			<bean id="Evictor"
					className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor/>
		</backingMapPluginCollection>
	</backingMapPluginCollections>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridBean.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
TranPropListener tranPropListener = new TranPropListener();
companyGrid.addEventListener(tranPropListener);

BackingMap customerMap = companyGrid.defineMap("Customer");
Evictor lruEvictor = new com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor();
customerMap.setEvictor(lruEvictor);

Pour plus d'informations sur l'utilisation de ces plug-in Présentation des plug-in.

Elément property

L'élément property permet d'ajouter des propriétés aux plug-in. Le nom de la propriété doit correspondre à une méthode set sur la classe référencée par le bean qui la contient.
Attributs
name
Indique le nom de la propriété. La valeur affectée à cet attribut doit correspondre à une méthode set sur la classe fournie comme attribut className sur le bean qui la contient. Par exemple, si l'attribut className du bean a la valeur com.ibm.MyPlugin et que le nom de la propriété fournie est size, la classe com.ibm.MyPlugin doit avoir une méthode setSize. (Obligatoire)
type
Indique le type de la propriété. Le type est transmis à la méthode set identifiée par l'attribut name. Les valeurs valides sont les primitives Java, les équivalents java.lang et java.lang.String. Les attributs name et type doivent correspondre à une signature de méthode sur l'attribut className du bean. Par exemple, si vous spécifiez le nom size et le type int, une méthode setSize(int) doit exister sur la classe spécifiée comme attribut className pour le bean. (Obligatoire)
value
Indique la valeur de propriété. Cette valeur est convertie dans le type spécifié par l'attribut type, puis utilisée comme paramètre dans l'appel de la méthode set identifiée par les attributs name et type. La valeur de cet attribut n'est pas validée de quelque manière que ce soit. (Obligatoire)
description
Décrit la propriété. (Facultatif)
<bean
(1)	name="name"
(2)	type="java.lang.String" | "boolean" | "java.lang.Boolean" | "int" |
			 "java.lang.Integer" | "double" | "java.lang.Double" | "byte" |
			 "java.lang.Byte" | "short" | "java.lang.Short" | "long" | 
			 "java.lang.Long" | "float" | "java.lang.Float" | "char" | 
			 "java.lang.Character"
(3)	value="value"
(4)	description="description"
/>
Dans l'exemple ci-après, le fichier companyGridProperty.xml permet d'illustrer l'ajout d'un élément property à un bean. Dans cet exemple, une propriété dont le nom est maxSize et le type est int est ajoutée à un expulseur. La classe com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor possède une signature de méthode qui correspond à la méthode setMaxSize(int). La valeur d'entier 499 est transmise à la méthode setMaxSize(int) dans la classe com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			<backingMap name="Customer"
				pluginCollectionRef="customerPlugins"/>
		</objectGrid>
	</objectGrids>
	<backingMapPluginCollections>
		<backingMapPluginCollection id="customerPlugins">
			<bean id="Evictor"
					className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor>
					<property name="maxSize" type="int" value="449"
							description="The maximum size of the LRU Evictor"/>
			</bean>
		</backingMapPluginCollection>
	</backingMapPluginCollections>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridProperty.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

BackingMap customerMap = companyGrid.defineMap("Customer");

LRUEvictor lruEvictor = new com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor();
// Si le fichier XML est utilisé à la place,
// la propriété ajoutée génère l'appel suivant :
lruEvictor.setMaxSize(449);
customerMap.setEvictor(lruEvictor);

Elément backingMapPluginsCollections

L'élément backingMapPluginsCollections sert de conteneur à tous les éléments backingMapPluginCollection. Dans le fichier companyGridProperty.xml de la section précédente, l'élément backingMapPluginCollections contient un élément backingMapPluginCollection avec l'ID customerPlugins.

Elément backingMapPluginCollection

L'élément backingMapPluginCollection définit les plug-in BackingMap et est identifié par l'attribut id. Spécifiez l'attribut pluginCollectionRef pour référencer les plug-in. Si vous configurez plusieurs plug-in BackingMaps de manière similaire, chaque plug-in BackingMap peut faire référence au même élément backingMapPluginCollection.
Attributs
id
Identifie la collection de plug-in de mappe de sauvegarde et est référencé par l'attribut pluginCollectionRef de l'élément backingMap. Chaque ID doit être unique. Si la valeur d'un attribut pluginCollectionRef ne correspond pas à l'ID d'un élément backingMapPluginCollection, la validation XML échoue. Plusieurs éléments backingMap peuvent faire référence à un même élément backingMapPluginCollection. (Obligatoire)
<backingMapPluginCollection
(1)			id="id"
/>
Dans l'exemple ci-après, le fichier companyGridCollection.xml permet d'illustrer la manière d'utiliser l'élément backingMapPluginCollection. Dans ce fichier, la mappe de sauvegarde Customer utilise la collection de plug-in de mappe de sauvegarde customerPlugins pour se configurer avec un expulseur LRU. Les mappes de sauvegarde Item et OrderLine font référence à la collection de plug-in de mappe de sauvegarde collection2. Ces mappes de sauvegarde possède chacune un ensemble d'expulseurs LFU.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			<backingMap name="Customer"
				pluginCollectionRef="customerPlugins"/>
			<backingMap name="Item" pluginCollectionRef="collection2"/>
			<backingMap name="OrderLine"
				pluginCollectionRef="collection2"/>
			<backingMap name="Order"/>
		</objectGrid>
	</objectGrids>
	<backingMapPluginCollections>
		<backingMapPluginCollection id="customerPlugins">
			<bean id="Evictor"
					className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor/>
		</backingMapPluginCollection>
		<backingMapPluginCollection id="collection2">
			<bean id="Evictor"
					className="com.ibm.websphere.objectgrid.plugins.builtins.LFUEvictor/>
			<bean id="OptimisticCallback"
					className="com.ibm.websphere.samples.objectgrid.EmployeeOptimisticCallBackImpl"/>
		</backingMapPluginCollection>
		</backingMapPluginCollections>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridCollection.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();

ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
BackingMap customerMap = companyGrid .defineMap("Customer");
LRUEvictor customerEvictor = new LRUEvictor();
customerMap.setEvictor(customerEvictor);

BackingMap itemMap = companyGrid.defineMap("Item");
LFUEvictor itemEvictor = new LFUEvictor();
itemMap.setEvictor(itemEvictor);

BackingMap orderLineMap = companyGrid.defineMap("OrderLine");
LFUEvictor orderLineEvictor = new LFUEvictor();
orderLineMap.setEvictor(orderLineEvictor);

BackingMap orderMap = companyGrid.defineMap("Order");

Elément querySchema

L'élément querySchema définit les relations entre les mappes de sauvegarde et identifie le type d'objet dans chaque mappe. Ces informations sont utilisées par la requête d'objet pour convertir les chaînes du langage de requête en appels d'accès à la mappe. Pour plus d'informations, voir Configuration d'un schéma ObjectQuery.

Elément mapSchemas

Chaque élément querySchema possède un élément mapSchemas qui contient un ou plusieurs éléments mapSchema.

Elément mapSchema

Un élément mapSchema définit le type d'objet stocké dans une mappe de sauvegarde et les instructions d'accès aux données.
Attributs
mapName
Indique le nom de la mappe de sauvegarde à ajouter au schéma. (Obligatoire)
valueClass
Indique le type d'objet stocké dans la portion valeur de la mappe de sauvegarde. (Obligatoire)
primaryKeyField
Indique le nom de l'attribut de clé primaire dans l'attribut valueClass. La clé primaire doit également être stockée dans la partie clé de la mappe de sauvegarde. (Facultatif)
accessType
Identifie la manière dont le moteur de requête introspecte les données persistantes des instances d'objet valueClass et y accède. Si vous spécifiez la valeur FIELD, les zones de classe sont introspectées et ajoutées au schéma. Si la valeur est PROPERTY, les attributs associés aux méthodes get et is sont utilisés. La valeur par défaut est PROPERTY. (Facultatif)
<mapSchema
(1)			mapName="backingMapName"
(2)			valueClass="com.mycompany.OrderBean"
(3)			primaryKeyField="orderId"
(4)			accessType="PROPERTY" | "FIELD"
/>
Dans l'exemple ci-après, le fichier companyGridQuerySchemaAttr.xml permet d'illustrer un exemple de configuration mapSchema.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			<backingMap name="Order"/>
			<backingMap name="Customer"/>

			<querySchema>
				<mapSchemas>
					<mapSchema mapName="Order"
						valueClass="com.mycompany.OrderBean"
						primaryKeyField="orderNumber"
						accessType="FIELD"/>
					<mapSchema mapName="Customer"
						valueClass="com.mycompany.CustomerBean"
						primaryKeyField="id"
						accessType="FIELD"/>
				</mapSchemas>
			</querySchema>
		</objectGrid>
	</objectGrids>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridQuerySchemaAttr.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");

// Définissez le schéma
QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
    "Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
    "Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
companyGrid.setQueryConfig(queryCfg);

Elément relationships

Chaque élément querySchema possède zéro ou un élément relationships qui contient un ou plusieurs éléments relationship.

Elément relationship

Un élément relationship définit la relation entre deux mappes de sauvegarde et les attributs de l'attribut valueClass qui associent la relation.
Attributs
source
Indique le nom de la classe de valeur du côté source d'une relation. (Obligatoire)
target
Indique le nom de la classe de valeur du côté cible d'une relation. (Obligatoire)
relationField
Indique le nom de l'attribut dans la classe de valeur source qui fait référence à la cible. (Obligatoire)
invRelationField
Indique le nom de l'attribut dans la classe de valeur cible qui fait référence à la source. Si cet attribut n'est pas indiqué, la relation est unidirectionnelle. (Facultatif)
<mapSchema
(1)			source="com.mycompany.OrderBean"
(2)			target="com.mycompany.CustomerBean"
(3)			relationField="customer"
(4)			invRelationField="orders"
/>
Dans l'exemple ci-après, le fichier companyGridQuerySchemaWithRelationshipAttr.xml permet de montrer un exemple de configuration mapSchema qui contient une relation bidirectionnelle.
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">

	<objectGrids>
		<objectGrid name="CompanyGrid">
			<backingMap name="Order"/>
			<backingMap name="Customer"/>

			<querySchema>
				<mapSchemas>
					<mapSchema mapName="Order"
						valueClass="com.mycompany.OrderBean"
						primaryKeyField="orderNumber"
						accessType="FIELD"/>
					<mapSchema mapName="Customer"
						valueClass="com.mycompany.CustomerBean"
						primaryKeyField="id"
						accessType="FIELD"/>
				</mapSchemas>
				<relationships>
					<relationship
						source="com.mycompany.OrderBean"
						target="com.mycompany.CustomerBean"
						relationField="customer"/>
						invRelationField="orders"/>
				</relationships>
			</querySchema>
		</objectGrid>
	</objectGrids>
</objectGridConfig>
L'exemple de code suivant illustre l'approche par programme permettant d'obtenir la même configuration qu'avec le fichier companyGridQuerySchemaWithRelationshipAttr.xml de l'exemple précédent.
ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");

// Définissez le schéma
QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
    "Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
    "Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryRelationship(new QueryRelationship(
     OrderBean.class.getName(), CustomerBean.class.getName(), "customer", "orders"));
companyGrid.setQueryConfig(queryCfg);

Elément stream

L'élément stream représente un flux vers le moteur de requête de flux. Chaque attribut de l'élément stream correspond à une méthode de l'interface StreamMetadata.
Attributs
name
Indique le nom du flux. La validation échoue si cet attribut n'est pas spécifié. (Obligatoire)
valueClass
Indique le type de classe de la valeur stockée dans la mappe d'objets de flux. Le type de classe permet de convertir l'objet en événements de flux et de générer une instruction SQL si cette dernière n'est pas fournie. (Obligatoire)
sql
Indique l'instruction SQL du flux. Si cette propriété n'est pas fournie, du code SQL de flux est généré en reflétant les attributs ou les méthodes d'accès sur l'attribut valueClass ou en utilisant les attributs de bloc de données des métadonnées d'entité. (Facultatif)
access
Indique le type d'accès aux attributs de la classe de valeur. Si vous spécifiez la valeurFIELD, les attributs sont directement extraits des zones à l'aide de la réflexion Java. Sinon, les méthodes d'accès sont utilisées pour lire les attributs. La valeur par défaut est PROPERTY. (Facultatif)
<stream
(1)	name="streamName"
(2)	valueClass="streamMapClassType"
(3)	sql="streamSQL create stream stockQuote
				 keyed by t ( transactionvolume INTEGER, price DECIMAL (9,2), issue VARCHAR(100) );"
(4)	access="PROPERTY" | "FIELD"
/>

Elément view

L'élément view représente une vue de requête de flux. Chaque élément stream correspond à une méthode de l'interface ViewMetadata.
Attributs
name
Indique le nom de la vue. La validation échoue si cet attribut n'est pas spécifié. (Obligatoire)
sql
Indique le SQL du flux, qui définit la transformation de la vue. La validation échoue si cet attribut n'est pas spécifié. (Obligatoire)
valueClass
Indique le type de classe de la valeur stockée dans cette vue de la mappe d'objets. Le type de classe permet de convertir les événements de vue dans le format de nuplet approprié compatible avec ce type de classe. Si le type de classe n'est pas fourni, un format par défaut qui suit les définitions de colonne dans le langage SPTSQL (Stream Processing Technology Structured Query Language) est utilisé. Si les métadonnées d'une entité sont définies pour cette mappe de vues, n'utilisez pas l'attribut valueClass. (Facultatif)
access
Indique le type d'accès aux attributs de la classe de valeur. Si vous spécifiez le type d'accès FIELD, les valeurs des colonnes reçoivent directement les valeurs des zones à l'aide de la réflexion Java. Sinon, les méthodes d'accès sont utilisées pour définir les attributs. La valeur par défaut est PROPERTY. (Facultatif)
<view
(1)			name="viewName"
(2)			valueClass="viewMapValueClass"
(3)			sql="viewSQL CREATE VIEW last5MinuteAvgPrice AS
						SELECT issue, avg(price) as totalVolume
 					  FROM (SELECT * FROM stockQuote FETCH LATEST 5 MINUTES) group by issue;"/>
(4)			access="PROPERTY" | "FIELD"
/>

Elément basic

L'élément basic permet de définir un mappage entre le nom d'attribut de la classe de valeur ou les métadonnées d'entité et la colonne définie dans le langage SPTSQL.
<basic
(1)			name="attributeName"
(2)			column="columnName"
/>

Elément id

L'élément ID est utilisé pour un mappage d'attributs de clé.
<id
(1)			name="idName"
(2)			column="columnName"
/>