Benutzer können in einem POJO-Service eine weiße oder schwarze Liste für Methoden erstellen. Zum Erstellen einer weißen und schwarzen Liste wird das Attribut filter des Elements "methods" im POJO-Element verwendet. Mögliche Werte des Filters sind "whitelisting" und "blacklisting". Wenn der Filter nicht angegeben ist, werden alle Methoden aufgelistet. Die Methode "getAddress" der Klasse "AddressLookup" kann auf eine weiße Liste gesetzt werden, indem der POJO-Service wie im folgenden Beispiel angegeben wird.
Das Beispiel demonstriert, dass mit dem RPC-Adapter nur auf die Methode "getAddress" der Klasse "AddressLookup" zugegriffen werden kann. Dieselbe Methode kann wie im folgenden Beispiel auf eine schwarze Liste gesetzt werden.
Das obige Beispiel demonstriert, dass mit dem RPC-Adapter auf alle Methoden der Klasse "AddressLookup" mit Ausnahme von "getAddress" zugegriffen werden kann. Wenn das Element "methods" des POJO-Service oder das Attribut "filter" des Elements "methods" nicht angegeben ist, stehen standardmäßig alle Methoden auf der weißen Liste.
In vielen Fällen müssen Sie möglicherweise mit den Methoden, die von JavaScriptTM aufgerufen werden, auf ein HttpServletRequest-Objekt zugreifen. Dieses Ziel können wir mit dem RPC-Adapter erreichen, indem wir die Anforderung HttpServletRequest als ersten Parameter für den Methodenaufruf verwenden. Die zurückgegebene SMD (Simple Method Description) enthält das Objekt "HttpServletRequest" nicht als Parameter, so dass Sie die Methode vom JavaScript ohne Übergabe dieses Parameters aufrufen können. Nehmen wir beispielsweise eine Methode putNameInSession(HttpServletRequest req, String name). Die folgende XML wird angezeigt.
Prüfprogramme werden mit den validators-Elementen in der RPC-Adapterkonfigurationsdatei definiert. Sie können eine Gruppe von Prüfprogrammen für einzelne POJO-Services angeben. Vor dem Aufruf einer Methode wird die Methode "validate" des angegebenen Prüfprogramms für die Parameter der Methode aufgerufen. Sie können für jeden Methodenparameter ein eigenes Prüfprogramm angeben. Alle Prüfprogramme müssen eine Erweiterung der abstrakten Klasse "com.ibm.websphere.rpcadapter.Validator" sein. Eine weitere Möglichkeit der Validierung ist die Verwendung regulärer Ausdrücke. Mit dem Element "validation-regex" können Sie reguläre Ausdrücke angeben, die mit den Parameterwerten abgeglichen werden müssen. Stimmen die Parameterwerte nicht mit den regulären Ausdrücken überein, wird ein Validierungsfehler erzeugt.
Bei Validierungsfehlern wird ein Fehlerobjekt im JSON-Format zurückgegeben. Sie können diese Informationen für die Fehlerbehandlung verwenden. Die Felder sind im Folgenden beschrieben.
Der RPC-Adapter unterstützt jetzt für die von ihm präsentierten Objekte Geltungsbereiche. Es gibt drei verschiedene unterstützte Bereiche: Anforderung (Request), Sitzung (Session) und Anwendung (Application). Ist der Geltungsbereich auf Application oder Session gesetzt, haben Sie den zusätzlichen Vorteil, dass das Objekt nicht jedes Mal neu erstellt, sondern im Bereich der Sitzung oder Anwendung gesucht wird. Der verwendete Schlüssel hat das Format "com.ibm.websphere.rpcadapter:ServiceName". Hier steht "ServiceName" für den Namen des präsentierten Objekts. Für diese Angabe dieses Schlüssels hat jedes Objekt ein Tag "scope", das die Werte "Session", "Request" und "Application" haben kann. Sehen Sie sich das folgende Beispiel an.
Der RPC-Adapter unterstützt jetzt das Hinzufügen von Rückgabewerten zur Sitzung. Hierfür müssen Sie das Tag <add-to-session> wie nachfolgend gezeigt hinzufügen.
Der RPC-Adapter unterstützt jetzt komplexe Objekte, z. B. Objekte, die weitere Objekte enthalten können. Komplexe Objekte werden als Rückgabetypen und als Methodenparameter unterstützt. Der RPC-Adapter kann jetzt komplexe Objekte aller Typen serialisieren. Zuordnungen und Datensammlungen werden allerdings nicht als Parameter von Methodenaufrufen unterstützt, weil die Klasse der Objekte in der Zuordnung/Datensammlung nicht allein aus ihrem Inhalt ermittelt werden kann. Eine entsprechende Unterstützung würde Hinweise auf Klassen oder Typen mit Parameterangabe erfordern, die noch nicht verfügbar sind. Außerdem können über HTTP-RPC keine Methoden mit komplexen Parametern aufgerufen werden, auch wenn komplexe Rückgabetypen unterstützt werden.
Diese Unterstützung ist ein Sonderfall der Unterstützung für komplexe Objekte. Beispiel: A -> B -> A (Objekt A enthält B, das wiederum A enthält). Der RPC-Adapter des Produkts handhabt solche Objekte, indem er die doppelten Vorkommen von Objekten durch $jref-Platzhalter (JSON-Serialisierung) oder $xref-Platzhalter (XML-Serialisierung) ersetzt. Die Informationen in diesen Platzhaltern können verwendet werden, um nach dem Originalobjekt zu suchen, d. h. im Falle von XML nach einem XPath-Ausdruck oder im Falle von JSON nach einem JavaScript-Ausdruck. Sie können die Unterstützung für die Handhabung rekursiver Objekte aktivieren, indem Sie das Tag <recursive-object-support> auf true setzen. Dies ist im folgenden Beispiel dargestellt.
Objekte, die präsentiert werden sollen, enthalten oft bestimmte Felder, die der Anwendungsentwickler nicht über den JSON- oder XML-Webservice offenlegen möchte. Mit dem RPC-Adapter können Felder des zurückgegebenen Objekts unterdrückt werden. Diese Unterdrückung wird mit dem Tag <serialized-params> aktiviert. Die für die Unterdrückung des Felds "postalCode" der Klasse "com.ibm.Address" erforderliche Konfiguration ist nachfolgend dargestellt. Diese Konfiguration hat zur Folge, dass das Feld "postalCode" der Klasse "com.ibm.Address" nicht serialisiert wird.
Der Benutzer kann Aliasnamen für Klassen angeben. Während der XML-Serialisierung wird der Aliasname als Knotenname verwendet. Das folgende Beispiel zeigt, wie der Aliasname für "address" konfiguriert werden kann.
Benutzer können Umsetzer für JSON/XML angeben. Wenn für eine Klasse ein Umsetzer angegeben ist, wird er für die JSON/XML-Serialisierung dieser
Klasse verwendet. Alle Umsetzerklassen müssen das Interface com.ibm.websphere.rpcadapter.converters.IConverter
implementieren. Der RPC-Adapter wird standardmäßig mit folgenden Umsetzern bereitgestellt.
Converter | Verwendung |
com.ibm.websphere.rpcadapter.converters.sql.Date
|
Konvertierung von java.sql.Date in eine Datums- und Zeitzeichenfolge. |
com.ibm.websphere.rpcadapter.converters.sql.Time
|
Konvertierung von java.sql.Time in eine Datums- und Zeitzeichenfolge. |
com.ibm.websphere.rpcadapter.converters.sql.TimeStamp
|
Konvertierung von java.sql.TimeStamp in eine Datums- und Zeitzeichenfolge. |
com.ibm.websphere.rpcadapter.converters.util.Date
|
Konvertierung von java.util.Date in eine Datums- und Zeitzeichenfolge. |
Sie können in "RpcAdapterConfig.xml" wie im folgenden Beispiel dargestellt Umsetzer angeben. Mit dem Tag <subclass-support> können Sie sogar angeben, dass die Unterklassen der angegebenen Bean-Klasse von der Umsetzerklasse umgesetzt werden sollen. Dazu müssen Sie den Wert zwischen den Tags auf "true" setzen. Standardmäßig ist diese Eigenschaft auf "false" gesetzt.
Wenn Methoden als JSON-Web-Services präsentiert werden sollen, können Sie den RPC-Adapter aus Sicherheitsgründen für Ausgaben konfigurieren, aus denen JSON-Kommentare, z. B. alle in "/*" und "*/" eingeschlossenen JSON-Daten, herausgefiltert sind. Dojo kann die JSON-Daten mit herausgefilterten Kommentaren auf der Clientseite verarbeiten. Dieses Feature des RPCAdapter ist standardmäßig inaktiviert. Sie können es aktivieren, indem Sie das Tag "filtered" in der Datei "RPCAdapterConfig.xml" auf "true" setzen. Sehen Sie sich dazu das folgende Beispiel an:
Für die Sicherheitsunterstützung verwendet der RPC-Adapter die Java-EE-Websicherheit. Alle Services, die für die Bereitstellung für den Client konfiguriert wurden, haben eindeutige URLs. Der Zugriff auf diese URLs ist nur über die Java-EE-Websicherheit möglich. Hierfür muss im Anwendungsserver ein Sicherheit-Realm erstellt werden. Anschließend muss der rollenbasierte Zugriff auf die verschiedenen URLs in der Implementierungsdeskriptordatei "web.xml" definiert werden. Die entsprechenden Rollen müssen dann über die serverspezifische Konfiguration Benutzern oder Gruppen im Sicherheits-Realm zugeordnet werden. Dieses Feature kann bei stapelorientierten Aufrufen nicht isoliert verwendet werden.
Zusätzlich zur Java-EE-Websicherheit kann der RPC-Adapter so konfiguriert werden, dass er Berechtigungsprüfungen für die verfügbaren Services ausführt und daher nur für bestimmte Rollen, die in web.xml oder geronimo-web.xml definiert sind, die Zugriffsberechtigung erteilt. Zur Nutzung dieses Features muss das URL-Muster "/RPCAdapter/*" über web.xml gesichert werden. Im nächsten Schritt wird der Tag <role> verwendet, um anzugeben, ob nur ein Benutzer in einer bestimmten Rolle die Zugriffsberechtigung für den entsprechenden Service erhält. Beachten Sie Folgendes: Der RPC-Adapter führt zwar die Serviceberechtigung aus, die Anwendung ist jedoch weiterhin dafür zuständig, den Benutzer vor dem Aufruf des gesicherten Service zu authentifizieren. Wird die Authentifizierung nicht vor dem Aufruf des gesicherten Service ausgeführt, lässt der RPC-Adapter den Zugriff auf den entsprechenden Service nicht zu. Dies gilt nur für Methoden im Service, die bereits in der Whitelist aufgeführt sind. Der Zugriff auf den Service kann wie unten dargestellt gesteuert werden.
Mit der Anwendungsprogrammierschnittstelle BatchService können Benutzer Aufrufe zu einem Stapel zusammenfassen. Es kann eine neue Stapelservicefactory erstellt, initialisiert und anschließend wie folgt übergeben werden.
Überladene Methoden können bereitgestellt werden, indem ein eindeutiger Name für die überladene Methode und die entsprechenden Parametertypen in der Datei "RpcAdapterConfig.xml" angegeben werden.
Sie können Methoden Namen zuordnen, die sich von den eigentlichen, in der Java-Implementierung verwendeten Namen, unterscheidet. Hierfür können die Tags <alias> und <name> auf ähnliche Weise wie beim Überladen von Methoden verwendet werden. Die einzige Ausnahme besteht darin, dass die Parametertypen nicht angegeben werden müssen, wenn die Methode nicht überladen ist.
Für den Zugriff auf Enterprise-Beans über den RPC-Adapter geben Sie die erforderlichen Informationen des EJB-Moduls in der Datei "RPCAdapterConfig.xml" an. Die Methoden im EJB-Moduls werden bereitgestellt, und Sie können eine Methode direkt über JavaScript aufrufen.
Für den Zugriff auf Session-Beans über den RPC Adapter geben Sie die fernen und lokalen Schnittstellen, den JNDI-Namen für die Suche des EJB-Moduls und die Methoden an, die implementiert werden.
Die fernen und und lokalen Schnittstellen der EJB Version 3.0 werden durch eine einzige Schnittstelle ersetzt, die gewöhnlich als Geschäftsschnittstelle bezeichnet wird.
Geben Sie die Geschäftsschnittstelle deshalb mit dem Tag <business-interface> an. Das Tag <ejb-name> wird verwendet, um dem EJB-Modul einen logischen Namen zuzuordnen.
Das Tag <jndi-name> wird verwendet, um EJB-Module zu suchen. Der vom Benutzer in der Datei "RPCAdapterConfig.xml" angegebene JNDI-Name muss mit dem JNDI-Namen übereinstimmen, der in der
Datei "web.xml" angegeben ist. In EJB Version 3.0 müssen Sie dem JNDI-Namen die
Angabe "java:comp/env/" als Präfix voranstellen, wenn der verwendete Anwendungsserver WebSphere® Application Server Community Edition ist. Wenn in WebSphere Application Server EJB Version 3.0
verwendet wird, muss der JNDI-Name im Tag <jndi-name> das Schlüsselwort "ejblocal:" als Präfix vorangestellt werden.
Den Typ der Session-Bean (stateless oder stateful) müssen Sie mit dem Tag <session-type> angeben.
Ein Beispieleintrag für eine Stateless-Session-Bean in der Datei "RPCAdapterConfig.xml" sehen Sie im Folgenden:
In Stateful-Session-Beans kann die Home-Schnittstelle mehrere Erstellungsfunktionen enthalten. Geben Sie in einem solchen Fall die Erstellungsfunktion an, die aufgerufen werden soll. Verwenden Sie das Tag <create>, um die Erstellungsfunktion in der Datei "RPCAdapterConfig.xml" zu deklarieren. Im Folgenden sehen Sie ein Code-Snippet für eine Stateful-Session-Bean der EJB 2.1.
Die Annotationsunterstützung ermöglicht Ihnen, Ihre Services direkt über den Code bereitzustellen, anstatt sie in der Datei "RPCAdapterConfig.xml" zu konfigurieren. Zum Aktivieren dieses Features wird in diesem Release die Datei RPCAdapter-annotation.jar bereitgestellt. Kopieren Sie diese JAR-Datei in das Verzeichnis "WEB-INF/lib" der Webanwendung, die dieses Feature verwendet. Sie müssen die Klasse, die mit @Pojo bereitzustellenden Methoden enthält, und die entsprechenden Methoden mit den Annotationen @Method und @Params annotieren. Eine annotierte Klasse wird dem RPC-Adapter über die Datei "web.xml" sichtbar gemacht. Geben Sie den kanonischen namen der annotierten Klasse als "init-param"-Wert für den RPC-Adapter an. Geben Sie den entsprechenden "init-param"-Namen mit classn an, wobei n für eine Zahl steht. Im Folgenden sehen Sie ein Beispielcode-Snippet.
Das Ausgabeformat des RPC-Adapters ist JSON oder XML.
Die verschiedenen XML-Ausgaben, die in den verschiedenen Szenarios generiert werden, sind im Folgenden aufgelistet.
Beim Rückgabetyp "void" ist die generierte XML-Ausgabe, wie im Folgenden gezeigt, ein leeres Ergebnis-Tag.
Wenn die Methode in der JavaBeans public int getSalary()
ist, gleicht die Ausgabe dem folgenden Beispiel:
public String getMessage()
ist, gleicht die Ausgabe dem folgenden Beispiel:
public Boolean isLeapYear(int year)
ist, gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp eine Datensammlung (Collection) ist, besteht die Ausgabe aus einer Reihe von Elementen, die jeweils einen Eintrag der Datensammlung repräsentieren. Enthält die Datensammlung Instanzen eines unterdrückten Objekttyps, wird dieser Eintrag ignoriert.
public Collection getEmployees()
ist und die zurückgegebene Datensammlung Instanzen von Employee enthält,
gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp ein Array ist, besteht die Ausgabe aus einer Reihe von Elementen, die jeweils einen Eintrag im Array repräsentieren.
public Employee[] getEmployees()
ist und der zurückgegebene Bereich aus Instanzen von "Employee" besteht,
gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp eine Zuordnung (Map) ist, besteht die Ausgabe aus einer Reihe von Elementen, die jeweils ein Schlüssel-Wert-Paar der Zuordnung repräsentieren. Der Knotenname ist der Schlüssel.
Wenn die Methode in der Java-Bean public Map getDepartments()
ist und die zurückgegebene Zuordnung ein Schlüssel-Wert-Paar
mit Abteilungscode und Abteilungsdetails ist, gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp "JavaBeans" ist, werden bei der XML-Serialisierung alle read-Methoden und öffentlichen Felder ohne read-Methode berücksichtigt. Die
Java-Bean wird durch ein Element dargestellt. Der Knotenname
dieses Elements ist der Typ der dargestellten Java-Bean. Falls für die Bean ein Alias
angegeben ist, wird dieser als Knotenname verwendet.
Wenn die Methode in der Java-Bean public Employee getEmployee()
ist, gleicht die Ausgabe dem folgenden Beispiel:
Die verschiedenen JSON-Ausgaben, die in den verschiedenen Szenarios generiert werden, sind im Folgenden erläutert.
Beim Rückgabetyp "void" ist die generierte JSON-Ausgabe ein JSON-Ergebnisobjekt.
public int getSalary()
ist, gleicht die Ausgabe dem folgenden Beispiel:
public String getMessage()
ist, gleicht die Ausgabe dem folgenden Beispiel:
public Boolean isLeapYear(int year)
ist, gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp eine Datensammlung ist, besteht die Ausgabe aus einer Reihe von Elementen, die jeweils einen Eintrag der Datensammlung repräsentieren. Enthält die Datensammlung Instanzen eines unterdrückten Objekttyps, wird dieser Eintrag ignoriert.
public Collection getEmployees()
ist und die zurückgegebene Datensammlung Instanzen von Employee enthält,
ähnelt die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp ein Array ist, besteht die Ausgabe aus einer Reihe von Elementen, die jeweils einen Eintrag im Array repräsentieren.
public Employee[] getEmployees()
ist und der zurückgegebene Bereich aus Instanzen von "Employee" besteht,
gleicht die Ausgabe dem folgenden Beispiel:
Wenn der Rückgabetyp eine Zuordnung ist, besteht die Ausgabe aus einer Reihe von Schlüssel-Wert-Paaren.
Wenn die Methode in der Java-Bean public Map getDepartments()
ist und die zurückgegebene Zuordnung ein Schlüssel-Wert-Paar
mit Abteilungscode und Abteilungsdetails ist, gleicht die Ausgabe dem folgenden Beispiel:
Die Java-Beans werden in Form von Schlüssel-Wert-Paaren dargestellt, wobei der Schlüssel der Name des Feldes und der Wert der Wert des Feldes ist. Es werden nur öffentliche Felder mit getter-Methoden serialisiert.
Wenn die Methode in der Java-Bean public Employee getEmployee()
ist, gleicht die Ausgabe dem folgenden Beispiel:
Der RPC-Adapter kann erstens für die Erstellung einer neuen JavaBeans-Instanz pro Anforderung und zweitens für die Wiederverwendung von Instanzen für einen Benutzer konfiguriert werden. (Die letztgenannte Konfiguration wäre beispielsweise für das Objekt eines elektronischen Warenkorbs möglich.) Das Standardverhalten ist die Erstellung einer neuen JavaBeans-Instanz pro Anforderung. Die Wiederverwendung wird über die Bean-Deskriptorinformationen konfiguriert. Weitere Einzelheiten finden Sie in der Dokumentation zur Anwendungsprogrammierschnittstelle "SampleBeanInfo".
Bei der Entwicklung einiger Befehle wird nicht vermutet, dass sie direkt als Services zugänglich gemacht werden könnten. In solchen Fällen kann ein JavaBeans-Zugriffsmechanismus für die implizierte Logik entwickelt werden. Die ShoppingCart-EJB im Beispiel Plants By WebSphere enthält eine Methode addItem(StoreItem item). Das StoreItem-Objekt enthält den Artikelpreis. Bei der Gestaltung wurde somit davon ausgegangen, dass die Methode nur von vertrauenswürdigen Quellen wie der folgenden im Servlet ShoppingServlet aufgerufen werden würde: