Zum Konfigurieren des REST-Datenservice bearbeiten Sie die Eigenschaftendatei für REST und definieren das erforderliche Entitätsschema für ein Datengrid.
Die Eigenschaftendatei des REST-Datenservice ist die Hauptkonfigurationsdatei für den REST-Datenservice von eXtreme Scale. Diese Datei ist eine Java-Eigenschaftendatei mit Schlüssel/Wert-Paaren. Standardmäßig sucht der REST-Datenservice eine ordnungsgemäß benannte Datei wxsRestService.properties im Klassenpfad. Diese Datei kann auch explizit mit der folgenden Systemeigenschaft definiert werden: wxs.restservice.props.
-Dwxs.restservice.props=/usr/configs/dataservice.properties
Beim Laden des REST-Datenservice wird die verwendete Eigenschaftendatei in den Protokolldateien angezeigt:
CWOBJ4004I: Die Eigenschaftendateien für den REST-Datenservice von eXtreme Scale REST wurden geladen: [/usr/configs/RestService.properties]
Die Eigenschaftendatei des REST-Datenservice unterstützt die folgenden Eigenschaften:
Eigenschaft | Beschreibung |
---|---|
catalogServiceEndPoints | Die erforderliche durch Kommas begrenzte Liste der Hosts und Ports einer
Katalogservicedomäne im Format <Host:Port>.
Diese Liste ist optional, wenn Sie WebSphere Application
Server integriert mit WebSphere eXtreme Scale für den REST-Datenservice verwenden.
Weitere Informationen hierzu finden Sie im Abschnitt Eigenständigen Katalogservice starten.
catalogServiceEndPoints= server1:2809,server2:2809 |
objectGridNames | Die erforderlichen Namen der Datengrids, die dem REST-Service bereitgestellt werden sollen.
Es ist mindestens ein ObjectGrid-Name erforderlich.
Wenn Sie mehrere ObjectGrid-Namen angeben, trennen Sie diese durch Kommas:
ECommerceGrid,InventoryGrid |
objectGridClientXML | Der optionale Name der XML-Datei für das Überschreiben von ObjectGrid-Clients.
Der hier angegebene Name wird aus dem Klassenpfad geladen.
Die Standardeinstellung ist wie folgt:
/META-INF/objectGridClient.xml. |
ogClientPropertyFile | Der optionale Name der ObjectGrid-Clienteigenschaftendatei. Diese Datei enthält Sicherheitseigenschaften, die für die Aktivierung der ObjectGrid-Clientsicherheit erforderlich sind. Wenn das Attribut "securityEnabled" in der Eigenschaftendatei gesetzt ist, wird die Sicherheit in dem vom REST-Service verwendeten ObjectGrid-Client aktiviert. Außerdem muss "credentialGeneratorProps" in der Eigenschaftendatei auf einen Wert mit dem Format "Benutzer:Kennwort" oder auf den Wert {xor_encoded Benutzer:Kennwort} zu setzen. |
loginType | Der Typ der vom REST-Service verwendeten
Authentifizierung, wenn die ObjectGrid-Clientsicherheit aktiviert ist.
Wenn die ObjectGrid-Clientsicherheit nicht aktiviert ist, wird diese Eigenschaft ignoriert.
Wenn die ObjectGrid-Clientsicherheit aktiviert ist und "loginType" auf basic gesetzt ist,
verwendet der REST-Service
Wenn die ObjectGrid-Clientsicherheit aktiviert ist und "loginType" auf none gesetzt ist,
verwendet der REST-Service
|
traceFile | Der optionale Name der Datei, an die die Traceausgabe umgeleitet wird. Die Standardeinstellung ist logs/trace.log. |
traceSpec | Die optionale Tracespezifikation, die der eXtreme-Scale-Laufzeitserver anfänglich verwenden soll. Die Standardeinstellung ist *=all=disabled. Zum Durchführen eines Trace für den gesamten REST-Datenservice verwenden Sie ObjectGridRest*=all=enabled. |
verboseOutput | Wenn diese Einstellung auf true gesetzt ist, empfangen Clients des REST-Datenservice zusätzliche Diagnoseinformationen, wenn Fehler auftreten. Die Standardeinstellung ist false. Diese optionale Einstellung sollte für Produktionsumgebungen auf "false" gesetzt werden, da sensible Informationen offengelegt werden können. |
maxResultsPerCollection | Die optionale maximale Anzahl an Ergebnissen, die in einer Abfrage zurückgegeben werden. Der Standardwert ist unlimited. Gültige Werte sind alle positiven ganzen Zahlen. |
wxsRestAccessRightsFile | Der optionale Name der Eigenschaftendatei für die Zugriffsrechte für den REST-Datenservice von eXtreme Scale, in der die Zugriffsrechte für die Serviceoperationen und die ObjectGrid-Entitäten angegeben sind. Wenn diese Eigenschaft angegeben ist, versucht der REST-Service, die Datei aus dem angegebenen Pfad zu laden. Andernfalls versucht er, die Datei aus seinem Klassenpfad zu laden. |
Der REST-Datenservice von eXtreme Scale interagiert mit eXtreme Scale über die API "EntityManager". Ein Entitätsschema wird für ein eXtreme-Scale-Datengrid definiert, und die Metadaten für die Entitäten werden automatisch vom REST-Datenservice konsumiert. Weitere Einzelheiten zum Konfigurieren eines Entitätsschemas finden Sie unter Entitätsschema definieren.
@Entity
public class Person {
@Id String taxId;
String firstName;
String lastName;
}
Der REST-Service erstellt automatisch ein ADO.NET-EDMX-Dokument (Entity Data Model Extensions), das unter dem URI "$metadata" verfügbar ist:
http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/$metadata
Wenn das Datengrid konfiguriert und aktiv ist, konfigurieren und packen Sie einen eXtreme-Scale-Client. Einzelheiten zum Konfigurieren des Clientpakets für den REST-Datenservice von eXtreme Scale finden Sie in den Informationen zum Packen und Implementieren in REST-Datenservice installieren.
Entitäten von WebSphere eXtreme Scale werden mithilfe der Entitätsannotationen oder einer Deskriptordatei für Entitätsmetadaten modelliert. Einzelheiten zum Konfigurieren eines Entitätsschemas finden Sie in Entitätsschema definieren. Der REST-Datenservice von eXtreme Scale verwendet die Entitätsmetadaten für die automatische Erstellung eines EDMX-Modells für den Datenservice.
Beispiel:
@Entity(schemaRoot=true)public class Person {
@Id String taxId;
String firstName;
String lastName;
@OneToMany(mappedBy="person")
List<Address> addresses;
}
@Entity
public class Address {
@Id int addrId;
@Id @ManyToOne Person person;
String street;
}
Das Protokoll "OData" definiert die folgende Liste von EDM-Typen (Entity Data Model) in seinem System abstrakter Typen. In den folgenden Abschnitten wird beschrieben, wie der REST-Adapter von eXtreme Scale den EDM-Typ auf der Basis des in der Entität definierten Basistyps auswählt. Einzelheiten zu EDM-Typen finden Sie auf der Webseite MSDN Library: Abstract Type System.
Die folgenden EDM-Typen sind in WCF Data Services verfügbar:
Der EDM-Typ "Edm.Guid" wird vom REST-Datenservice von eXtreme Scale nicht unterstützt.
Java-Typ | EDM-Typ |
---|---|
boolean java.lang.Boolean | Edm.Boolean |
byte java.lang.Byte | Edm.SByte |
short java.lang.Short | Edm.Int16 |
int java.lang.Integer | Edm.Int32 |
long java.lang.Long | Edm.Int64 |
float java.lang.Float | Edm.Single |
double java.lang.Double | Edm.Double |
java.math.BigDecimal | Edm.Decimal |
java.math.BigInteger | java.math.BigInteger |
java.lang.String | Edm.String |
char | char |
java.lang.Character | java.lang.Character |
Char[] | Char[] |
java.lang.Character[] | java.lang.Character[] |
java.util.Calendar | Edm.DateTime |
java.util.Date | java.util.Date |
java.sql.Date | java.sql.Date |
java.sql.Timestamp | java.sql.Timestamp |
java.sql.Time | java.sql.Time |
Weitere Typen | Edm.Binary |
Für Update- und Insert-Anforderungen geben die Nutzdaten die im REST-Datenservice von eXtreme Scale zu aktualisierenden bzw. einzufügenden Daten an. Der Service kann kompatible Datentypen automatisch in die im EDMX-Dokument definierten Datentypen konvertieren. Der REST-Datenservice konvertiert die XML-codierten Zeichenfolgedarstellungen des Werts in dem folgenden Prozess, der sich aus zwei Schritten zusammensetzt, in den richtigen Typ:
EDM-Typ | Java-Typ |
---|---|
Edm.Boolean | Boolean java.lang.Boolean |
Edm.SByte | Byte java.lang.Byte short java.lang.Short int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger char java.lang.Character |
Edm.Byte, Edm.Int16 | short java.lang.Short int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger char java.lang.Character |
Edm.Int32 | int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger |
Edm.Int64 | long java.lang.Long double java.lang.Double java.math.BigDecimal java.math.BigInteger |
Edm.Double | double java.lang.Double java.math.BigDecimal |
Edm.Decimal | double java.lang.Double java.math.BigDecimal java.math.BigInteger |
Edm.Single | float java.lang.Float double java.lang.Double java.math.BigDecimal |
Edm.String | java.lang.String char java.lang.Character Char[] java.lang.Character[] java.math.BigDecimal java.math.BigInteger |
Edm.DateTime | java.util.Calendar java.util.Date java.sql.Date java.sql.Time java.sql.Timestamp |
Edm.Time | java.sql.Time java.sql.Timestamp |
Java enthält fünf Zeittypen für das Speichern von Datum und/oder Uhrzeit: java.util.Date, java.sql.Date, java.sql.Time, java.sql.Timestamp und java.util.Calendar. Alle Typen werden im Entitätsdatenmodell als "Edm.DateTime" ausgedrückt. Der REST-Datenservice von eXtreme Scale konvertiert und normalisiert die Daten automatisch abhängig vom Java-Typ. In diesem Abschnitt werden verschiedene Punkte beschrieben, die Entwickler bei der Verwendung von Zeittypen beachten müssen.
Unterschiede zwischen Zeitzonen
In WCF Data Services werden die Beschreibungen von Zeitwerten im Typ "Edm.DateTime" immer mit dem UTC-Standard (Coordinated Universal Time, koordinierte Weltzeit) ausgedrückt. UTC ist der international bekannte Name für GMT (Greenwich Mean Time, mittlere Greenwich-Zeit). Die koordinierte Weltzeit ist die Zeit, die am Nullmeridian, dem UTC-Ursprung, gemessen wird. In der koordinierten Weltzeit gibt es keine Sommerzeit.
Konvertierung von Entitäts- in EDM-Typen und umgekehrt
Wenn ein Client eine Anforderung an den REST-Datenservice sendet, werden Datum und Uhrzeit als Zeit in der GMT-Zeitzone dargestellt. Beispiel:
"2000-02-29T21:30:30.654123456"
Der REST-Datenservice erstellt anschließend die entsprechende Java-Zeittypinstanz und fügt diese in die Entität im Datengrid ein.
Wenn ein Client eine Eigenschaft anfordert, die ein Java-Zeittyp aus dem REST-Datenservice von eXtreme Scale ist, wird der Wert immer als GMT-Zeitzonenwert normalisiert. Beispiel für eine wie folgt aufgebaute java.util.Date-Entität:
Calendar c = Calendar.getInstance();
c.clear();
c.set(2000, 1, 29, 21, 30, 30);
Date d = c.getTime();
Datum und Uhrzeit werden mit der Standardzeitzone des Java-Prozesses dargestellt, weil Calendar.getInstance() ein Calendar-Objekt mit der lokalen Zeitzone erstellt. Wenn die lokale Zeitzone CST ist, hat das vom REST-Datenservice abgerufene Datum die GMT-Zeitdarstellung: "2000-03-01T03:30:30"
Normalisierung von java.sql.Date
Eine eXtreme-Scale-Entität kann ein Attribut dem Java-Typ "java.sql.Date" definieren. Dieser Datentyp enthält keine Uhrzeit und wird vom REST-Datenservice normalisiert. Das bedeutet, dass die Laufzeitumgebung von eXtreme Scale keine Stunden, Minuten, Sekunden oder Millisekunden im Attribut "java.sql.Date" speichern. Ungeachtet der Zeitzonendifferenz wird das Datum immer als lokales Datum dargestellt.
Wenn der Client beispielsweise eine java.sql.Date-Eigenschaft mit dem Wert "2009-01-01T03:00:00" aktualisiert, erstellt der REST-Datenservice, der sich in der Zeitzone CST (-06:00) befindet, einfach eine java.sql.Date-Instanz, deren Uhrzeit auf "2009-01-01T00:00:00" der lokalen CST-Zeit gesetzt wird. Es wird keine Zeitzonenkonvertierung durchgeführt, um den java.sql.Date-Wert zu erstellen. Wenn der REST-Serviceclient den Wert dieses Attributs abruft, wird dieser als "2009-01-01T00:00:00Z" angezeigt. Würde eine Zeitzonenkonvertierung durchgeführt, hätte der angezeigte Wert das Datum "2008-12-31", das falsch wäre.
Normalisierung von java.sql.Time
Ähnlich wie bei java.sql.Date werden die java.sql.Time-Werte normalisiert und enthalten keine Datumsinformationen. Das bedeutet, dass die Laufzeitumgebung von eXtreme Scale Jahr, Monat und Tag nicht speichert. Die Uhrzeit wird unter Verwendung der GMT-Zeit ab dem 1. Januar 1970 gespeichert, die mit der java.sql.Time-Implementierung konsistent ist.
Wenn der Client beispielsweise eine java.sql.Time-Eigenschaft mit dem Wert "2009-01-01T03:00:00" speichert, erstellt der REST-Datenservice eine java.sql.Time-Instanz, in der die Millisekunden auf "3*60*60*1000" (entspricht 3 Stunden) gesetzt sind. Wenn der REST-Service den Wert abruft, wird dieser als "1970-01-01:03:00:00Z" angezeigt.
Assoziationen definieren die Beziehung zwischen zwei Peer-Entitäten. Der REST-Service von eXtreme Scale spiegelt die Assoziationen wider, die mit Entitäten, die mit annotierten eXtreme-Scale-Entitäten definiert werden, oder mit in einer XML-Entitätsdeskriptordatei definierten Entitäten modelliert sind.
Verwaltung von Assoziationen
Der REST-Datenservice von eXtreme Scale unterstützt keine referenziellen Integritätsbedingungen. Der Client muss sicherstellen, dass Referenzen aktualisiert werden, wenn Entitäten entfernt oder hinzugefügt werden. Wenn die Zielentität einer Assoziation aus dem Datengrid entfernt wird, aber die Verbindung zwischen der Quellen- und der Zielentität nicht, ist die Verbindung beschädigt. Der REST-Datenservice von eXtreme Scale und die API "EntityManager" tolerieren beschädigte Verbindungen und protokollieren diese in Form von CWPRJ1022W-Warnungen. Beschädigte Assoziationen werden aus den Nutzdaten der Anforderung entfernt.
Verwenden Sie eine Stapelanforderung, um Assoziationsaktualisierungen in einer einzigen Transaktion durchzuführen, um beschädigte Verbindungen zu vermeiden. Einzelheiten zu Stapelanforderungen finden Sie im folgenden Abschnitt.
Das Element "ReferentialConstraint" des ADO.NET-Entitätsdatenmodells wird vom REST-Datenservice von eXtreme Scale nicht verwendet.
Assoziationsmultiplizität
Entitäten können Assoziation mit mehreren Werten oder mit einem einzelnen Wert haben. Assoziationen mit mehreren Werten oder Sammlungen sind 1:N- oder N:N-Assoziationen. Assoziationen mit einem einzelnen Wert sind 1:1- oder N:1-Assoziationen.
In einem partitionierten Datengrid müssen alle Entitäten einen Schlüsselassoziationspfad mit einem einzelnen Wert zu einer Stammentität haben. In einem anderen Abschnitt dieses Artikels wird beschrieben, wie eine Schlüsselassoziation definiert wird. Da die Stammentität für die Partitionierung der Entität verwendet wird, sind N:N-Assoziationen für partitionierte Datengrids nicht zulässig. Ein Beispiel für die Modellierung eines relationalen Entitätsschemas für ein partitioniertes Datengrid finden Sie unter Skalierbares Datenmodell in eXtreme Scale.
Im folgenden Beispiel wird beschrieben, wie die Assoziationstypen der API "EntityManager", die mit annotierten Java-Klassen modelliert werden, dem ADO.NET-Entitätsdatenmodell zugeordnet werden:
@Entity
public class Customer {
@Id String customerId;
@OneToOne TaxInfo taxInfo;
@ManyToOne Address homeAddress;
@OneToMany Collection<Order> orders;
@ManyToMany Collection<SalesPerson> salespersons;
}
<Association Name="Customer_TaxInfo">
<End Type="Model1.Customer" Role="Customer" Multiplicity="1" />
<End Type="Model1.TaxInfo " Role="TaxInfo" Multiplicity="1" />
</Association>
<Association Name="Customer_Address">
<End Type="Model1.Customer" Role="Customer" Multiplicity="1" />
<End Type="Model1.Address" Role="TaxInfo" Multiplicity="*" />
</Association>
<Association Name="Customer_Order">
<End Type="Model1.Customer" Role="Customer" Multiplicity="*" />
<End Type="Model1.Order" Role="TaxInfo" Multiplicity="1" />
</Association>
<Association Name="Customer_SalesPerson">
<End Type="Model1.Customer" Role="Customer" Multiplicity="*" />
<End Type="Model1.SalesPerson" Role="TaxInfo" Multiplicity="*" />
</Association>
Bidirektionale und unidirektionale Assoziationen
Entitätsassoziationen können unidirektional oder bidirektional sein. Durch die Angabe des Attributs "mappedBy" in der Annotation @OneToOne, @OneToMany oder @ManyToMany oder des Attributs "mapped-by" im XML-Attribut-Tag "one-to-one", "one-to-many" oder "many-to-many" wird die Entität bidirektional. Das Protokoll "OData" erfordert derzeit, dass alle Entitäten bidirektional sind, was den Clients ermöglicht, Navigationspfade in beide Richtungen zu generieren. Die API "EntityManager" von eXtreme Scale ermöglicht die Modellierung unidirektionaler Assoziationen, wodurch Speicher eingespart und die Verwaltung der Assoziationen vereinfacht werden kann. Wenn eine unidirektionale Assoziation verwendet wird, dürfen die Clients des REST-Datenservice nur über die definierte Assoziation navigieren.
Beispiel: Wenn eine unidirektionale N:1-Assoziation zwischen Address und Country definiert ist, ist der folgende URI nicht zulässig.
/restservice/CustomerGrid/Country('USA')/addresses
Schlüsselassoziationen
Assoziationen mit einem Einzelwert (1:1 und N:1) können auch als vollständiger oder partieller Entitätsschlüssel eingeschlossen werden. Dies wird als Schlüsselassoziation bezeichnet.
Schlüsselassoziationen sind erforderlich, wenn ein partitioniertes Datengrid verwendet wird. Die Schlüsselassoziation muss für alle untergeordneten Entitäten in einem partitionierten Entitätsschema definiert werden. Das Protokoll "OData" erfordert, dass alle Entitäten direkt adressierbar sind. Das bedeutet, dass der Schlüssel in der untergeordneten Entität den für die Partitionierung verwendeten Schlüssel enthalten muss.
Im folgenden Beispiel hat Customer eine 1:N-Assoziation zu Order. Die Entität "Customer" ist die Stammentität, und das Attribut "customerId" wird für die Partitionierung der Entität verwendet. Order enthält Customer als Teil seiner Identität:
@Entity(schemaRoot="true")
public class Customer {
@Id String customerId;
@OneToMany(mappedBy="customer") Order orders
}
@Entity
public class Order {
@Id int orderId;
@Id @ManyToOne Customer customer;
java.util.Date orderDate;
}
Wenn der REST-Datenservice das EDMX-Dokument für dieses Modell generiert, werden die Schlüsselfelder von Customer automatisch in die Entität "Order" eingeschlossen:
<EntityType Name="Order">
<Key>
<PropertyRef Name="orderId"/>
<PropertyRef Name="customer_customerId"/>
</Key>
<Property Name="orderId" Type="Edm.Int64" Nullable="false"/>
<Property Name="customer_customerId" Type="Edm.String"
Nullable="false"/>
<Property Name="orderDate" Type="Edm.DateTime" Nullable="true"/>
<NavigationProperty Name="customer"
Relationship="NorthwindGridModel.Customer_orders"
FromRole="Order" ToRole="Customer"/>
<NavigationProperty Name="orderDetails"
Relationship="NorthwindGridModel.Order_orderDetails"
FromRole="Order" ToRole="OrderDetail"/>
</EntityType>
Wenn eine Entität erstellt wird, darf sich der Schlüssel nie ändern. Wenn die Schlüsselassoziation zwischen einer untergeordneten Entität und der übergeordneten Entität geändert werden muss, muss deshalb die untergeordnete Entität entfernt und mit einer anderen übergeordneten Entität neu erstellt werden. In einem partitionierten Datengrid erfordert dies zwei verschiedene Stapeländerungssets, da von der Verschiebung wahrscheinlich mehrere Partitionen betroffen sind.
Kaskadierende Operationen
Die API "EntityManager" unterstützt eine flexible Kaskadierungsrichtlinie. Assoziationen können für die Kaskadierung einer persist-, remove-, invalidate- oder merge-Operation markiert werden. Solche Kaskadierungsoperationen können auf einer oder beiden Seiten einer bidirektionalen Assoziation vorkommen.
Das Protokoll "OData" lässt kaskadierende delete-Operationen nur auf der 1-Seite der Assoziation zu. Die Annotation "CascadeType.REMOVE" bzw. das XML-Attribut "cascade-remove" können nicht auf beiden Seiten einer bidirektionalen 1:1-Assoziation bzw. auf der N-Seite einer 1:N-Assoziation definiert werden. Das folgende Beispiel veranschaulicht eine gültige bidirektionale Cascade.REMOVE-Assoziation:
@Entity(schemaRoot="true")
public class Customer {
@Id String customerId;
@OneToMany(mappedBy="customer", cascade=CascadeType.REMOVE)
Order orders
}
@Entity
public class Order {
@Id int orderId;
@Id @ManyToOne Customer customer;
java.util.Date orderDate;
}
Die generierte EDMX-Assoziation sieht folgendermaßen aus:
<Association Name="Customer_orders">
<End Type="NorthwindGridModel.Customer" Role="Customer"
Multiplicity="1">
<OnDelete Action="Cascade"/>
</End>
<End Type="NorthwindGridModel.Order" Role="Order"
Multiplicity="*"/>
</Association>