Gestionnaire d'entités dans un environnement distribué

Vous pouvez utiliser l'API EntityManager avec un ObjectGrid local ou dans un environnement distribué eXtreme Scale. La principale différence réside dans le mode choisi pour se connecter à cet environnement. Une fois la connexion établie, il n'existe aucune différence entre l'utilisation d'un objet Session et l'utilisation de l'API EntityManager.

Fichiers de configuration requis

Les fichiers de configuration XML suivants sont requis :
  • Fichier XML descripteur d'ObjectGrid
  • Fichier XML descripteur d'entité
  • Fichier de déploiement ou XML descripteur de la grille de données

Ces fichiers indiquent les entités et les mappes BackingMaps qu'un serveur héberge.

Le fichier descripteur des métadonnées d'entité contient une description des entités utilisées. Vous devez au minimum définir la classe et le nom de l'entité. Si votre environnement d'exécution est un environnement Java Platform, Standard Edition 5, eXtreme Scale lit automatiquement la classe d'entités et ses annotations. Vous pouvez définir des attributs XML supplémentaires si la classe d'entités n'est associée à aucune annotation ou si vous devez remplacer les attributs de classe. Si vous enregistrez les entités sans classe, entrez toutes les informations relatives à l'entité uniquement dans le fichier XML.

Vous pouvez utiliser le fragment de code XML suivant pour définir une grille de données et ses entités. Dans ce fragment, le serveur crée un ObjectGrid avec le nom bookstore et une mappe de sauvegarde associée nommée order. Le fichier de fragment objectgrid.xml fait référence au fichier entity.xml. Dans ce cas, le fichier entity.xml contient une entité, l'entité Order.

objectgrid.xml
<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="bookstore" entityMetadataXMLFile="entity.xml">
     <backingMap name="Order"/>
    </objectGrid>
</objectGrids>

</objectGridConfig>

Le fichier objectgrid.xml indique le fichier entity.xml avec l'attribut entityMetadataXMLFile. La valeur peut être un répertoire relatif ou un chemin absolu.
  • 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://.
Voici un exemple de fichier entity.xml :
entity.xml
<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="com.ibm.websphere.tutorials.objectgrid.em.
				distributed.step1.Order" name="Order"/>
</entity-mappings>
Cet exemple suppose que la classe Order a les zones orderNumber et desc annotées de la même manière.

Un fichier sans classe équivalent entity.xml se présente comme suit :

classless entity.xml
<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="@Order " name="Order">
	    <description>"Entity named: Order"</description>
        <attributes>
            <id name="orderNumber" type="int"/>
            <basic name="desc" type="java.lang.String"/>
        </attributes>
	</entity>
</entity-mappings>
Pour plus d'informations sur le démarrage des serveurs, voir Démarrage des serveurs autonomes. Vous utilisez les fichiers deployment.xml et objectgrid.xml pour démarrer le serveur de catalogue.

Connexion à un serveur eXtreme Scale réparti

Le code suivant active le mécanisme de connexion pour un client et un serveur installés sur le même ordinateur :
String catalogEndpoints="localhost:2809";
URL clientOverrideURL= new URL("file:etc/emtutorial/distributed/step1/objectgrid.xml");
ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, clientOverrideURL);
ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");
Notez la référence au serveur eXtreme Scale distant. Une fois la connexion établie, vous pouvez appeler les méthodes de l'API EntityManager telles que persist, update, remove et find.
Avertissement : Si vous utilisez des entités, transmettez le fichier XML descripteur d'ObjectGrid de remplacement par les clients à la méthode connect. Si la valeur null est transmise à la propriété clientOverrideURL et que la structure des répertoires du client soit différente de celle du serveur, le client risque de ne pas parvenir à localiser le fichier XML descripteur d'ObjectGrid ou le fichier XML descripteur d'entité. Vous pouvez au moins copier ces fichiers du serveur vers le client.
Pour utiliser des entités sur le client ObjectGrid, vous deviez auparavant mettre le fichier XML ObjectGrid et le fichier XML d'entité à la disposition du client de l'une des deux façons suivantes :
  1. En transmettant un fichier XML ObjectGrid de remplacement à la méthode ObjectGridManager.connect(String catalogServerEndpoints, ClientSecurityConfiguration securityProps, URL overRideObjectGridXml).

    String catalogEndpoints="myHost:2809";
    URL clientOverrideURL= new URL("file:etc/emtutorial/distributed/step1/objectgrid.xml");
    ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, clientOverrideURL);
    ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");

  2. En transmettant la valeur null pour le fichier de remplacement et en vérifiant que le fichier XML ObjectGrid et le fichier XML d'entité se trouvent dans le même chemin sur le client et sur le serveur.

    String catalogEndpoints="myHost:2809";
    ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, null);
    ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");

Que vous souhaitiez ou non utiliser des entités de sous-ensemble côté client, les fichiers XML étaient jusqu'alors nécessaires. Ils ne le sont désormais plus pour utiliser les entités telles qu'elles sont définies par le serveur. Vous pouvez simplement transmettre la valeur null comme paramètre pour overRideObjectGridXml, comme dans l'option 2 de la précédente section. Si le fichier XML ne se trouve pas dans le même chemin défini sur le serveur, le client utilise la configuration d'entité sur le serveur.

Toutefois, si vous utilisez des entités de sous-ensemble sur le client, vous devez fournir un fichier XML ObjectGrid de remplacement, comme dans l'option 1.

Client et schéma côté serveur

Le schéma côté serveur définit le type de données stockées dans les mappes du serveur. Le schéma côté client est un mappage du schéma du serveur vers les objets application. Voici un exemple de schéma côté serveur :
@Entity
class ServerPerson
{
  @Id String ssn;
  String firstName;
  String surname;
  int age;
  int salary;
}
Un objet du client peut être annoté de la façon suivante :
@Entity(name="ServerPerson")
class ClientPerson
{
  @Id @Basic(alias="ssn") String socialSecurityNumber;
  String surname;
}
Ce client prend alors une entité côté serveur et projette le sous-ensemble de l'entité vers l'objet client. Cette projection permet d'économiser de la bande passante et de la mémoire sur le client car celui-ci obtient uniquement les informations dont il a besoin, et non pas la totalité des informations se trouvant dans l'entité côté serveur. Des applications différentes peuvent utiliser leurs propres objets plutôt que contraindre toutes les applications à partager un ensemble de classes en vue de l'accès aux données.

Le fichier XML descripteur d'entité côté client est requis dans les cas suivants : si le serveur s'exécute avec des entités basées sur les classes alors que le côté client s'exécute sans classe, ou l'inverse. Le mode client sans classe permet au client d'exécuter les requêtes d'entité sans avoir accès aux classes physiques. Supposons que le serveur ait enregistré l'entité ServerPerson ci-dessus. Le client remplacerait la grille de données par un fichier entity.xml, tel que :

<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="@ServerPerson " name="Order">
	    <description>"Entity named: Order"</description>
        <attributes>
            <id name="socialSecurityNumber" type="java.lang.String"/>
            <basic name="surname" type="java.lang.String"/>
        </attributes>
	</entity>
</entity-mappings>

Ce fichier a pour effet de créer une entité de sous-ensemble équivalente dans le client, ce qui dispense ce dernier de fournir la classe annotée réelle. Si le serveur est sans classe alors que le client ne l'est pas, le client fournit un fichier XML descripteur d'entités dans lequel la référence au fichier classe est remplacée. Ce fichier XML contient un remplacement de la référence au fichier de classes.

Référencer le schéma

Si votre application s'exécute dans Java SE 5, vous pouvez ajouter l'application aux objets à l'aide d'annotations. EntityManager peut lire le schéma à partir de celles-ci. L'application fournit à l'environnement d'exécution eXtreme Scale les références à ces objets via le fichier entity.xml référencé par le fichier objectgrid.xml. Le fichier entity.xml répertorie toutes les entités, chacune de celles-ci étant associée à une classe ou à un schéma. Si un nom de classe correct est indiqué, l'application tente de lire les annotations Java SE 5 dans ces classes pour identifier le schéma. Si vous n'annotez pas le fichier classe ou que vous indiquiez un identificateur sans classe en tant que nom de classe, le schéma est extrait du fichier XML. Ce fichier permet de définir les attributs, clés et relations pour chaque entité.

Une grille de données locale n'a pas besoin d'un fichier XML. Le programme peut obtenir une référence ObjectGrid et appeler la méthode ObjectGrid.registerEntities pour définir une liste de classes annotées Java SE 5 ou un fichier XML.

L'environnement d'exécution utilise le fichier XML ou une liste des classes annotées pour rechercher les noms d'entité, les noms et les types des attributs, les zones et les types de clé, ainsi que les relations entre les entités. Si eXtreme Scale s'exécute sur un serveur ou en mode autonome, il crée immédiatement des mappes nommées d'après le nom de chaque entité. Vous pouvez personnaliser ces mappes à l'aide du fichier objectgrid.xml ou des API définies par l'application ou par les structures d'injection telles que Spring.

Fichier descripteur des métadonnées d'entité

Pour plus d'informations sur le fichier descripteur des métadonnées, consultez la section Fichier emd.xsd.