EntityManager in einer verteilten Umgebung

Sie können die API EntityManager mit einem lokalen ObjectGrid oder in einer verteilten eXtreme-Scale-Umgebung verwenden. Der Hauptunterschied besteht darin, wie Sie die Verbindung zu dieser fernen Umgebung herstellen. Nach dem Aufbau einer Verbindung besteht kein Unterschied mehr zwischen der Verwendung eines Session-Objekts und der Verwendung der API "EntityManager".

Erforderliche Konfigurationsdateien

Die folgenden XML-Konfigurationsdateien sind erforderlich:
  • ObjectGrid-XML-Deskriptordatei
  • XML-Deskriptordatei der Entität
  • XML-Deskriptordatei der Implementierung oder des Datengrids

Diese Dateien geben die Entitäten und BackingMaps an, die ein Server hostet.

Die Deskriptordatei für Entitätsmetadaten enthält eine Beschreibung der verwendeten Entitäten. Sie müssen mindestens die Entitätsklasse und den Entitätsnamen angeben. Wenn Sie in einer Umgebung mit Java Platform, Standard Edition 5 arbeiten, liest eXtreme Scale automatisch die Entitätsklasse und die zugehörigen Annotationen. Sie können weitere XML-Attribute definieren, wenn die Entitätsklasse keine Annotationen hat oder wenn Sie die Klassenattribute überschreiben müssen. Wenn Sie diese Entitäten klassenlos registrieren, geben Sie alle Entitätsinformationen ausschließlich in der XML-Datei an.

Sie können das folgende XML-Konfigurations-Snippet verwenden, um ein Datengrid mit Entitäten zu definieren. In diesem Snippet erstellt der Server ein ObjectGrid mit dem Namen bookstore und eine zugehörige BackingMap mit dem Namen order. Das Snippet aus der Datei objectgrid.xml verweist auf die Datei entity.xml. In diesem Fall enthält die Datei entity.xml eine Entität, die Entität "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>

Diese Datei objectgrid.xml gibt die Datei entity.xml mit dem Attribut entityMetadataXMLFile an. Der Wert kann ein relatives Verzeichnis oder ein absoluter Pfad sein.
  • Für ein relatives Verzeichnis: Geben Sie die Position relativ zur Position der Datei objectgrid.xml an.
  • Für einen absoluten Pfad: Geben Sie die Position mit einem URL-Format an, wie z. B. file:// oder http://.
Es folgt ein Beispiel für die Datei 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>
In diesem Beispiel wird davon ausgegangen, dass die Felder orderNumber und desc in der Klasse "Order" ähnlich annotiert sind.

Im Folgenden sehen Sie die entsprechende Datei entity.xml ohne Klassen:

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>
Informationen zum Starten von Servern finden Sie in Eigenständige Server starten. Sie können die Datei deployment.xml und die Datei objectgrid.xml zum Starten des Katalogservers verwenden.

Verbindung zu einem verteilten Server von eXtreme Scale herstellen

Der folgende Code aktiviert den Verbindungsmechanismus für einen Client und einen Server auf demselben Computer:
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");
Beachten Sie im vorherigen Code-Snippet die Referenz auf den fernen Server von eXtreme Scale. Nach dem Aufbau einer Verbindung können Methoden der API "EntityManager" wie persist, update, remove und find aufrufen.
Achtung: Wenn Sie Entitäten verwenden, übergeben Sie die neue XML-Deskriptordatei des Clients für das ObjectGrid an die Methode "connect". Wird ein Nullwert an die Eigenschaft "clientOverrideURL" übergeben und hat der Client eine andere Verzeichnisstruktur als der Server, kann der Client die ObjectGrid-XML-Deskriptordatei oder die XML-Deskriptordatei der Entität möglicherweise nicht finden. Zumindest können die XML-Dateien für das ObjectGrid und die Entitäten für den Server in den Client kopiert werden.
Zuvor hat die Verwendung von Entitäten in einem ObjectGrid-Client erfordert, dass die ObjectGrid-XML und die Entitäts-XML dem Client auf eine der folgenden Arten bereitgestellt wurde:
  1. Übergeben Sie eine überschreibende ObjectGrid-XML an die Methode 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. Übergeben Sie null für die Überschreibungsdatei, und stellen Sie sicher, dass die ObjectGrid-XML und die referenzierte Entitäts-XML für den Client in demselben Pfad wie auf dem Server verfügbar sind.

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

Die XML-Dateien waren erforderlich, unabhängig davon, ob Sie Teilentitäten auf der Clientseite verwenden möchten oder nicht. Diese Dateien sind nicht mehr erforderlich, um die vom Server definierten Entitäten zu verwenden. Übergeben Sie stattdessen null für den Parameter "overRideObjectGridXml" wie in Option 2 des vorherigen Schritts. Wenn die XML-Datei nicht in dem Pfad gefunden wird, der auf dem Server definiert wurde, verwendet der Client die Entitätskonfiguration auf dem Server.

Wenn Sie jedoch Teilentitäten auf dem Client verwenden, müssen Sie eine überschreibende ObjectGrid-XML wie in Option 1 bereitstellen.

Client- und serverseitiges Schema

Das serverseitige Schema definiert den Typ der Daten, die in den Maps auf einem Server gespeichert sind. Das clientseitige Schema ist eine Zuordnung zu den Anwendungsobjekten aus dem Schema im Server. Sie könnten beispielsweise das folgende serverseitige Schema haben:
@Entity
class ServerPerson
{
  @Id String ssn;
  String firstName;
  String surname;
  int age;
  int salary;
}
Ein Client könnte ein Objekt haben, das wie im folgenden Beispiel annotiert ist:
@Entity(name="ServerPerson")
class ClientPerson
{
  @Id @Basic(alias="ssn") String socialSecurityNumber;
  String surname;
}
Dieser Client verwendet anschließend eine serverseitige Entität und projiziert das Subset der Entität in das Clientobjekt. Diese Projektion führt zu Bandbreiten- und Speichereinsparungen auf einem Client, weil der Client nur die Informationen besitzt, die er benötigt, und nicht alle Informationen, die in der serverseitigen Entität enthalten sind. Anwendungen können ihre eigenen Objekte verwenden, anstatt sie dazu zu zwingen, einen Satz von Klassen für den Datenzugriff gemeinsam zu nutzen.

Die clientseitige XML-Entitätsdeskriptordatei ist erforderlich, wenn der Server mit klassenbasierten Entitäten ausgeführt wird, während auf der Clientseite klassenlose Entitäten ausgeführt werden, oder wenn der Server klassenlos ist und der Client klassenbasierte Entitäten verwendet. Im klassenlosen Clientmodus kann der client trotzdem Entitätsabfragen ausführen, ohne Zugriff auf die physischen Klassen zu haben. Davon ausgehend, dass der Server die vorherige Entität "ServerPerson" registriert habt, überschreibt der Client das Datengrid wie folgt mit einer Datei 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="@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>

Mit dieser Datei wird eine entsprechende Teilentität auf dem Client erreicht, ohne dass der Client die eigentliche annotierte Klasse bereitstellen muss. Wenn der Server klassenlos ist und der Client nicht, stellt der Client eine überschreibende XML-Entitätsdeskriptordatei bereit. Diese XML-Entitätsdeskriptordatei enthält einen Korrekturwert für die Klassendateireferenz.

Referenzierung des Schemas

Wenn Ihre Anwendung in Java SE 5 ausgeführt wird, kann die Anwendung über Annotationen den Objekten hinzugefügt werden. Der EntityManager kann das Schema aus den Annotationen in diesen Objekten lesen. Die Anwendung stellt der Laufzeitumgebung eXtreme Scale Referenzen auf diese Objekte in der Datei entity.xml bereit, die in der Datei objectgrid.xml referenziert wird. In der Datei entity.xml sind alle Entitäten aufgelistet, denen jeweils eine Klasse oder ein Schema zugeordnet ist. Wenn ein richtiger Klassenname angegeben ist, versucht die Anwendung, die Annotationen der Java SE Version 5 aus diesen Klassen zu lesen, um das Schema zu bestimmen. Wenn Sie die Klassendatei nicht annotieren oder eine klassenlose Kennung als Klassennamen angeben, wird das Schema aus der XML-Datei verwendet. Die XML-Datei wird verwendet, um alle Attribute, Schlüssel und Beziehungen für jede Entität anzugeben.

Ein lokales Datengrid benötigt keine XML-Dateien. Das Programm kann eine ObjectGrid-Referenz anfordern und die Methode ObjectGrid.registerEntities aufrufen, um eine Liste mit annotierten Klassen der Java SE Version 5 oder eine XML-Datei anzugeben.

Die Laufzeitumgebung verwendet die XML-Datei oder eine Liste mit annotierten Klassen, um Entitätsnamen, Attributnamen und -typen, Schlüsselfelder und -typen sowie Beziehungen zwischen Entitäten zu suchen. Wenn eXtreme Scale in einem Server oder im eigenständigen Modus ausgeführt wird, wird automatisch eine Map erstellt, die nach der jeweiligen Entität benannt wird. Diese Maps können über die Datei objectgrid.xml oder APIs, die von der Anwendung oder von Injektions-Frameworks wie Spring definiert werden, weiter angepasst werden.

Deskriptordateien für Entitätsmetadaten

Weitere Informationen zur Deskriptordatei für Metadaten finden Sie im Abschnitt Datei emd.xsd.