Neues Standardverhalten in XPages: Whitelist für Datenquellen

22. Juni 2015 Posted by Thomas Ladehoff

IBM Domino Designer
Seit Domino 9.0.1 FixPack 4 gibt es eine Neuerung bei XPages-Datenquellen, womit jetzt nicht mehr beliebige Servernamen über den URL übergeben werden können.

Bis zu diesem Update war es möglich über den URL Parameter "databaseName" einen anderen Server und Datenbank an eine XPage zu übergeben. Die Parameter werden von der Datenquelle auf der XPage verwendet, sofern nicht die Option ignoreRequestParams="true" für die Datenquelle gesetzt ist.

Mit dem neuen Update werden andere Server, als der aktuelle, standardmäßig nicht mehr zugelassen. Eine Beispieladresse wie die folgende führt dann zu dem Fehler "The databaseName URL parameter value is not one of the allowed database names.":

http ://servername.example.com/discussion.nsf/allDocuments.xsp?search=agenda&databaseName=otherserver!!discussion_data.nsf


Über eine neue Option in der xsp.properties Datei der XPages-Anwendung (bzw. des Servers) können die erlaubten Server und Datenbanken konfiguriert werden:

xsp.data.domino.param.databaseName.whitelist=<currentServer>!!<anyApplication>, otherServer!!app.nsf, otherServer!!app2.nsf


Darüber hinaus gibt zwei weitere neue Optionen für xsp.properties Datei:
  • xsp.data.domino.ignoreRequestParams = false
    Bei setzen auf "true" werden anwendungsweit auf XPages die übergebenen Parameter ignoriert.
  • xsp.data.domino.param.databaseName.usage= whitelist | apply | ignore | error
    Separates steuern des "databaseName"-Parameters. "whitelist" ist das Standardverhalten seit Domino 9.0.1 FixPack 4, davor war es "apply" (uneingeschränkt anwenden), bei "ignore" oder "error" wird der Parameter generell ignoriert bzw. führt zu einem Fehler. Empfehlenswerte Einstellung ist hier "ignore", sofern man diesen Parameter nicht wirklich benötigt.


Quelle und weitere Informationen: Link
Read full article |Kommentare deaktiviert für Neues Standardverhalten in XPages: Whitelist für Datenquellen
Tags: , ,
Categories: Allgemein

Einrichtung eines Domino Directory Catalog

29. Juli 2013 Posted by Thomas Ladehoff

DominoAdmin_90x90.png
Ein Directory Catalog dient zum Vorhalten von Adressen für die Notes Clients, die nicht Bestandteil des primären Domino Directory sind.

In diesem Blogeintrag geht es um die Einrichtung eines "Condensed Directory Catalog" (deutsche Varainte: Verzeichnis-Katalog).


Ein guter Anwendungsfall ist zum Beispiel das folgende Scenario: Die Mitarbeiter sollen neben den internen Adressen auch direkt beim Schreiben einer E-Mail weitere externe Adressen im "An"-Feld aus einer Liste wählen können.
Die externen Adressen sind in Form von Personen-Dokumenten über verschiedene Domino Directories verteilt (z.B. aus Gründen der einfacheren Verwaltung, verschiedene Domains und Zuständigkeiten usw.).
Ziel ist es all diese zusätzlichen Adressen den Mitarbeitern an einem zentralen Punkt zur Verfügung zu stellen.
Ein praktikabler Weg führt hier über einen Condensed Directory Catalog.
Dieser wird in Form einer eigenen Datenbank angelegt und über einen eigens dafür vorgesehenen Domino Task (der Directory Cataloger) mit den Adressen aus einer Menge von Domino Directories befüllt.

Der Directory Catalog wird dann auf die Clients repliziert und dort verwendet, womit sämtliche Adressen auch im Offline-Modus zur Verfügung stehen. Als Nebeneffekt erfolgt eine schnelle automatische Vervollständigung und Aufbau der Vorschlagsliste bei Eingabe der E-Mail Adresse in einer Mail (da Adressen lokal).

Nun zum Vorgehen bei der Einrichtung:
1. Anlegen eines neuen Directory Catalogs von der Schablone "dircat5.ntf" (mit Volltextindex):

A picture named M2


Hinweis: Der Titel der Datenbank wird später als Eintrag bei den verfügbaren Adressbüchern im Dialog zur Adressauswahl erscheinen.


2. Konfiguration des Directory Catalog:

A picture named M3


Folgende Punkte sind dabei zu beachten:
Wenn auch Mail-Verteiler bzw. Gruppen genutzt werden sollen, ist es erforderlich ein zusätzliches Feld "Members" mit zu den zusätzlichen Feldern aufzunehmen.
Dadurch werden auch die Mitglieder der Gruppen in den Directory Catalog übernommen und eine Client-seitige Auflösung der Ziel-Adressen wird möglich.
Eine Server-seitige Gruppenauflösung ist bei dem hier beschriebenen Ansatz nicht vorgesehen und allgemein werden Server-seitige Condensed Directory Catalogs auch seit der Domino Version 8.5.2 nicht mehr unterstützt.
Soll Server-seitig ein Adress-Lookup stattfinden (z.B. wenn weitere Dinge, wie Autorisierung abgewickelt werden sollen), ist ein Extended Directory Catalog das Mittel der Wahl.


In einer Umgebung mit mehreren Servern sollte der Directory Cataloger Task nur auf einem Server aktiv werden. Ansonsten können Replikationskonflikte entstehen.
In der Konfiguration ist der entsprechende Server zu hinterlegen (im Screenshot Feld "Restrict aggregation to this server").



3. Aktivierung des Directory Cataloger Task über den Domino Administrator:

A picture named M4


Für den ersten Lauf des Tasks bzw. wenn der Directory Catalog neu aufgebaut wird kann der Task auch manuell gestartet werden mit

load dircat dircat.nsf

auf der Server Konsole oder ohne Angabe der Datenbank um den Task auf Dauer zu starten.


4. Automatisches Verteilen des Directory Catalog an die Clients:
Die geschieht mit Hilfe eines  Desktop-Einstellung-Dokuments.

A picture named M5

Wenn die Einstellung dann mittels einer Policy an die Clients verteilt wurde, wird automatisch bei der nächsten Anmeldung eines Benutzers eine neue lokale Replik des Directory Catalog angelegt.

Hinweis: Bei der Aggregation der Personendokumente in den Katalog ist darauf zu achten, dass diese nur berücksichigt werden, wenn ein Benutzername angegeben ist. Ansonsten werden die betreffenden Dokuemten nicht mit übernommen.
Read full article |Kommentare deaktiviert für Einrichtung eines Domino Directory Catalog
Tags:
Categories: Allgemein

Erweiterung der XPages Extension Library REST Services

5. September 2012 Posted by Thomas Ladehoff

Domino-Designer-Logo-small.png
Mit den vorhandenen REST-Funktionen der Extension Library kommt man bereits sehr weit und kann unter anderem die Standard CRUD-Operationen (Create, Read, Update, Delete) abdecken. Es gibt jedoch Fälle, in denen man noch weitere Anforderungen hat, die eine Anpassung bzw. Erweiterung der bestehenden Funktionalität wünschenswert machen.

Nachdem im letzten Blogeintrag zum Thema REST die Grundlagen und die Verwendung der entsprechenden XPages Controls behandelt wurden, geht es in diesem Beitrag um eine Erweiterungsmöglichkeit mit Hilfe eines Custom Database Servlets.
Die REST-Funktionalität (Representational State Transfer) der Extension Library bietet verschiedene Arten der Erweiterung, um an die eigenen Bedürfnisse angepasst zu werden. Unter anderem stehen folgende Möglichkeiten zur Verfügung:
  • XPages Control "Custom REST Service" (xe:restService) aus der Extension Library.
Dieses Control bietet große Freiheit, weil keinerlei Vorgaben zur Ausgabe gemacht werden. Zur Verarbeitung von Anfragen kann Server Side JavaScript (SSJS) für die jeweiligen HTTP-Methoden hinterlegt werden (Control-Eigenschaften: "doGet", "doPost", "doPut", "doDelete").
  • Erstellen eines "Custom Database Servlets" in Java
Über ein Custom Database Servlet lässt sich sowohl Verarbeitung als auch die generierte Ausgabe komplett steuern, ohne dabei vordefinierten Mustern zu folgen. Dieses Vorgehen eignet sich auch, um die bestehenden Services in der Extension Library anzupassen.
  • Erstellen eines Custom Wink Servlet
Ein mit dem Apache Wink Projekt erstellter RESTful Service wird direkt in das OSGI Framework vom Domino Server installiert und hat Datenbank-übergreifenden Zugriff (siehe auch OpenNTF).

In den folgenden Abschnitten wird die Erstellung eines Custom Database Servlets anhand eines konkreten Beispiels erklärt, das auch als Ansatz für eigene Umsetzungen herangezogen werden kann.




Ein wenig Theorie
Die eigentliche Verarbeitung der REST-Anfragen wird von einer Klasse übernommen, die das Interface "com.ibm.domino.services.ServiceEngine" aus der Extension Library implementiert.
Eine solche Klasse könnte man z.B. selbst erstellen und dann der Laufzeitumgebung zur Abarbeitung von Anfragen zur Verfügung stellen (wie Letzteres geht wird weiter unten erklärt).
Alternativ kann man eine bestehende Klasse aus der Extension Library benutzen und deren Funktion durch Ableitung entsprechend erweitern oder abändern.

Die Klasse zur Operation auf Dokumenten (die auch im folgenden Beispiel verwendet wird) heißt "RestDocumentJsonService".
Wenn Sie etwas tiefer einsteigen möchten: Die Klasse ist im Package "com.ibm.domino.services.rest.das.document" im Plugin "com.ibm.domino.services" enthalten (den Quellcode gibt's im extension library download).
Es existieren unter anderem Methoden zum Lesen und Erstellen von Dokumenten ("renderServiceJSONGet" bzw. "createDocument"). Doch der zentrale Einstiegspunkt zum Verarbeitungsbeginn wird durch das genannte ServiceEngine-Interface vorgegeben und zwar durch die Methode "processRequest".

Die Klasse RestDocumentJsonService implementiert allerdings nicht direkt das Interface ServiceEngine sondern erbt noch von diversen weiteren Klassen.
Die Vererbungshierachie sieht dann etwas verkürzt wie folgt aus (inkl. eigener Klasse).

A picture named M2


Der REST Service wird über eine URL in der folgenden Form erreichbar sein:
http://{host}/{database}/xsp/services/{pathInfo}/unid/{unid}

Die Extension Library sorgt dafür, dass Anfragen vom Client mit entsprechender URL an das dafür vorgesehene ServiceEngine-Objekt zur Verarbeitung weitergereicht werden.
Die Zuordnung erfolgt hierbei über den URL-Teil "pathInfo".
Der nächste Schritt besteht also darin, der Laufzeitumgebung mitzuteilen, welcher pathInfo-String von welchem Objekt verarbeitet werden soll.

Dies geschieht über eine Factory-Klasse, die für die Erzeugung von Instanzen der richtigen Klasse zuständig ist.

Das Schema der Factory-Klasse sieht wie folgt aus:



(Neben dem folgenden Beispiel kann ein weiteres übrigens auch in der Extension Library Demo Datenbank gefunden werden.)

Kurze Erklärung:
Die Erstellung eines ServiceEngine-Objekts (z.B. ein RestDocumentJsonService-Objekt) erfolgt in der Methode "createEngine" (Zeile 9), welche Teil des ServiceFactory-Interface ist.
Ein entsprechendes ServiceFactory-Object wird hier an eine übergeordnete "DefaultServiceFactory" übergeben (Methode "addFactory, Zeile 7).
An dieser Stelle wird auch festgelegt, welcher Service letztendlich die Verarbeitung für welchen pathInfo-String bzw. URL übernimmt.
Die DefaultServiceFactory wird wiederum von einer übergeordneten ServletFactory-Klasse verwendet.


Was jetzt noch fehlt, ist das Registrieren der ServletFactory-Klasse, damit die Laufzeitumgebung sie finden und verwenden kann.
Dies geschieht über eine Textdatei mit dem Namen "com.ibm.xsp.adapter.servletFactory", die in einem Verzeichnis "META-INF/services" abgelegt werden muss.
In die Datei muss der (voll qualifizierte) Name der ServletFactory-Klasse eingetragen werden.

Klassen und Textdatei werden in einem Verzeichnis abgelegt, welches in den Build-Pfad des Projekts integriert werden muss.
Im Domino Designer in der Java-Perspektive könnte das im Ergebnis dann z.B. so aussehen, wie im folgenden Screenshot gezeigt (bereits ein Vorgriff auf das Beispiel):


A picture named M3



Erstellen eines Custom Database Servlets
Als Beispiel soll die Klasse RestDocumentJsonService erweitert werden, und zwar soll vor dem Speichern eines Dokuments eine Validierung stattfinden.
Bei nicht erfolgreicher Validierung sollen entsprechende Meldungen zum Client geschickt werden, die dieser ggf. direkt dem Benutzer anzeigen kann.
Prinzipiell ließe sich eine Validierung auch über das Konfigurieren des RestDocumentJsonService-Objekts mit der Eigenschaft "computeWithForm" erreichen, in Zusammenhang mit entsprechenden Validierungsformeln in der jeweiligen Maske.
Die im Folgenden vorgestellte Lösung bietet eine Alternative hierzu und hat auch verschiedene Vorteile gegenüber der "computeWithForm"-Variante.

Zur Umsetzung eines Services, der die Eingaben validiert müssen nur zwei Methoden der Basisklasse RestDocumentJsonService überschrieben werden:
  • Methode querySaveDocument
Diese Methode dient zur Ausführung von Code vor dem Speichern des Dokuments (analog zu dem entsprechenden XPages-Datenquellen-Ereignis). Auch für die anderen Dokumentenereignisse (open, new, delete) existieren Methoden.
Die querySaveDocument-Methode wird in diesem Beispiel dazu benutzt die Validierung auszuführen. Wenn die Validierung fehlschlägt, wird eine "ServiceValidationException" geworfen (siehe Codeausschnitt weiter unten).
  • Methode displayError
Diese Methode dient zur Generierung einer Fehlermeldung für den Client, wenn generell während der Verarbeitung etwas schief läuft und eine Exception auftritt.
Das Überschreiben der Methode erlaubt das Generieren einer benutzerdefinierten Nachricht für den Client, für den speziellen Fall einer fehlgeschlagenen Validierung.


Insgesamt sind für dieses Beispiel drei Klassen nötig:
  • ValidatingDocumentService-Klasse zur Implementierung des REST Services
  • ServiceValidationException zur Anzeige von Validierungsfehlern
  • ServletFactory-Klasse zur Erzeugung der Services


Die beiden Methoden "querySaveDocument" und "displayError" sind im Folgenden dargestellt. Das Beispiel zeigt die Validierung von Dokumenten vom Typ "company", also Firmendokumente (gleiches Szenario, wie im letzten Artikel).
Der gesamte Quellcode kann am Ende dieses Artikels heruntergeladen werden.




Die Validierung besteht der Einfachheit halber in diesem Fall nur aus einer einzelnen Prüfung des Feldes "CompanyName" auf Inhalt (Zeile 18).
Sollte die Prüfung nicht erfolgreich sein, wird eine entsprechende Exception geworfen, die auch als Container für die Fehlernachrichten der Validierung fungiert (Zeile 25).
In der Methode "displayError" wird dann geprüft, ob der Fehler von einer fehlgeschlagenen Validierung verursacht wurde, indem der Exception-Typ geprüft wird (Zeile 39).
Falls dies der Fall ist, werden die Fehlernachrichten zum Client geschickt (Zeile 53; Methode"writeJSONValidationException" siehe Download). Andernfalls wird der Standard-Mechanismus zur Fehlerausgabe benutzt (Zeile 61).




Test der API
Zum Testen des Services kann das Firefox Add-on RESTClient verwendet werden (siehe auch voriger Blogeintrag).

Das Ergebnis sieht dann wie folgt aus:
A picture named M4



Clients können einfach die Antwort analysieren, indem Sie bei einem Fehler (Code 500) die Eigenschaft "type" auswerten und die Nachrichten anzeigen.




Weitere Bemerkungen
Bei meinen Tests trat beim ersten Aufruf des Services eine "java.security.AccessControlException" auf. Dies ist auf die unterschiedlichen Security-Kontexte der Extension Library Laufzeitumgebung auf der einen Seite und der NSF-basierten Klassen auf der anderen Seite zurückzuführen (ohne die Ableitung der Klasse RestDocumentJsonService gibt es keine Exception). Trotz Exception scheint keine Einschränkung in der Funktion zu bestehen (zumindest so weit meine Tests reichten).




Download
Read full article |Kommentare deaktiviert für Erweiterung der XPages Extension Library REST Services
Tags: , ,
Categories: Allgemein

REST Services mit der XPages Extension Library

13. August 2012 Posted by Thomas Ladehoff

Domino-Designer-Logo-small.png
Die Benutzung von REST-basierten Services ist eine sehr schöne Möglichkeit andere Systeme und Anwendungen mit dem Lotus Domino Server zu integrieren.
Dieser Blogeintrag fasst die Bedeutung und Vorzüge von REST im Allgemeinen zusammen und zeigt die Grundlagen der Benutzung der REST Controls innerhalb der XPages Extension Library.

REST-basierte (oder RESTful) Webservices sind sowohl für Integrationsszenarios nützlich als auch zur Vorhaltung von Daten für externe Anwendungen.
Ich benutzte die REST Services zum Beispiel kürzlich, um eine Schnittstelle für eine mobile Anwendung zu realisieren.

RESTful Webservices (Falls Sie sie noch nicht kannten..)
Representational State Transfer (REST) bezeichnet einen Software-Architekturstil, der von Roy Thomas Fielding in seiner Dissertation beschrieben wurde und der Architektur des Internets entspricht. Genauer gesagt ist das im Internet und durch RESTful Webservices verwendete HTTP-Protokoll eine Implementierung des REST-Architekturstils.

Wenn Sie also die Prinzipien des HTTP-Protokolls kennen, wissen Sie auch schon viel über REST. Um die wichtigsten Punkte zu nennen:
  • Informationen werden mittels sogenannter Ressourcen zu Verfügung gestellt. Jede Ressource kan eindeutig über eine ID angesprochen werden (die URL).
  • "Respresentational" meint das Übertragen der Informationen in verschiedenen Repräsentationen, also Formaten. Das heißt sowohl im technischen Sinne (z.B. JSON, XML) als auch im inhaltlichen Sinne (z.B. Text, Bilder).
  • Zustandslosigkeit. Der Server behält keinen (Session-) Status über eine Folge von Requests.
  • Ressourcen können Verknüpfungen zu anderen Ressourcen enthalten, wodurch eine Navigation ermöglicht wird.
  • Die Operationen, die auf einer Ressource ausgeführt werden können, sind generischer Form. Typischerweise werden folgende vier verwendet:
    • GET - lesender Zugriff auf eine Ressource, frei von Seiteneffekten
    • POST - Erstellen einer neuen Ressource
    • PUT - Erstellen oder Aktualisieren einer bestimmten Ressource (bestimmte ID)
    • DELETE - Löschen einer Ressource

RESTful Webservices stellen einen auf HTTP basierenden Service bereit, der den genannten Prinzipien folgt.


Einige generelle Vorteile von RESTful Webservices sind:
  • Loose Kopplung von Anwendungen und Systemen (führt zu hoher Interoperabilität)
  • Einfaches Ressourcen-orientiertes Konzept mit wenigen generischen Methoden
  • Gute Skalierbarkeit
  • Einfaches Caching

Im Wesentlichen sind dies auch die Vorzüge des HTTP-Protokolls.



REST-basierte Services zum Zugriff auf Domino-Daten
Eine gute Übersicht über die REST-Funktionen in der Extension Library bietet das Video "REST Services for Domino and XPages" auf der Extension Library Homepage.
An dieser Stelle werde ich insbesondere die Benutzung der XPages Controls für REST vorstellen. Es gibt noch zwei alternative Wege, die außerhalb des XPages Kontext funktionieren (Benutzung des Domino Data Service und Erstellen eines Custom Servlets).

Es gibt verschiedene XPages Controls, die man zum Zugriff auf Domino-Daten benutzen kann. Zum Beispiel:
  • Database Collection Service (xe:databaseCollectionJsonService): Abrufen einer Datenbankliste auf dem Server.
  • View Collection ervice (xe:viewCollectionJsonService): Abrufen einer Liste von Ansichten und Ordnern in einer Datenbank.
  • View Service (xe:viewJsonService): Lesen von Ansichts- und Ordnerdaten (mit Filterung), Erstellen, Aktualisieren und Löschen von Dokumenten (begrenzt).
  • Document Service (xe:documentJsonService): Operationen auf Dokumenten.

Wie Sie vielleicht erahnen, steht das "Json" innerhalb der Tags der Controls für das verwendete Übertragungsformat JSON.

Beispiele der Controls können auch in der Beispieldatenbank innerhalb des Extension Library Downloads gefunden werden.

Für die XPages REST Controls ist es nicht erforderlich etwas auf dem Domino Server zu konfigurieren (aber es bringt eine kleine Vereinfachung, wie wir später sehen werden).
Es genügt eine XPage zu erstellen und die gewünschten REST Controls hinzuzufügen, um Zugriff auf die gewünschten Daten zu ermöglichen.

Um dies detaillierter zu zeigen und die wichtigsten Paramter zu erklären, werden wir ein einfachen Beispielszenario mit einer Maske "company" und einer Ansicht "companiesByName" verwenden.

Die Services, die wir benötigen, um in bequemer Weise mit den Firmendokumenten zu arbeiten sind:
  • xe:viewJsonService (Auflistung bestehender Firmen)
  • xe:documentJsonService (Erstellen, Lesen, Aktualisieren, Löschen bestimmter Firmendokumente)

Es ließe sich auch der View JSON Service zum Ändern von Dokumenten benutzen. In diesem Fall ist man jedoch auf die Felder im Dokument beschränkt, die direkt einer Ansichtsspalte zugeordnet sind.
Mit dem Document JSON Service lassen sich sogar Rich Text Felder und Anhänge lesen und bearbeiten.



Zugriff auf die Ansichtsdaten
Wir starten mit einer leeren XPage und dem Hinzufügen eines REST Service Controls (siehe Screenshot)
A picture named M2


Einige Eigenschaften dieses Controls:
  • ignoreRequestParams: Parameter in der URL werden für den REST Service ignoriert (analog zu der gleichnamigen Eigenschaft der XPages Datenquellen)
  • pathInfo: Dieser String identifiziert den Service auf der XPage. Für den View JSON Service in diesem Beispiel ist diese Eigenschaft "companies".
  • service: Hier wird der konkrete REST Service angegeben, einer der Services aus der Liste (siehe Screenshot). Im Beipiel der "xe:viewJsonService".


Die Eigenschaften des View JSON Service sind über die hinterlegten Beschreibungen schon fast selbsterklärend. Trotzdem hier ein paar wichtige:
  • columns: Für diese Eigenschaft werden Elemente vom Typ "xe:restViewColumn" angegeben, welche wiederum eine Eigenschaft "columnName" (Referenz zur Ansichtsspalte) und "name" (Eigenschaftsname des JSON Objekts in der Ausgabe). Letzteres Mapping wird nur bei GET Requests angewendet. Außerdem gibt es hier noch eine Eigenschaft "value", die zur Berechnung einer Wertes benutzt werden kann.
  • defaultColumns: Wenn "true", werden alle Spalten der Ansicht in die Ausgabe einbezogen.
  • systemColumns: Spezielle System Spalten, die nicht notwendigerweise als benutzerdefinierte Spalten angegeben sein müssen (z.B. UNID, Maskenname, Anwortdokument (ja/nein)).
  • viewName: Name der Ansicht, die für diesen REST Service benutzt werden soll.

Außerdem gibt es einige Eigenschaften zur Filterung der zurückgegebenen Ergebnisliste, wie z.B. "start" und "count" zur Realisierung von Paging, oder "search" zur Volltextsuche.
Auch Ereignisse zur Reaktion auf Dokumentenereignisse, wie "querysaveDocument" stehen zur Verfügung. Diese werden weiter unten erklärt.

Der folgende Screenshot zeigt die View Service Eigenschaften, die in diesem Beispiel benutzt wurden:
A picture named M3




Testen der API
Um auf den Service zuzugreifen, muss der für die Eigenschaft "pathInfo" angegebene String verwendet werden. Das generelle URL Schema im XPages Kontext ist:
http://{Host}/{Datenbank}/{XPage Name}/{pathInfo}/unid/{unid}?{Parameter}

Für den View Service in diesem Beipiel ist es nicht erfoderlich auf einzelne Dokumente zuzugreifen, daher kann der UNID-Teil weggelassen werden.
Angenommen, die Datenbank heißt "Test1.nsf" und die XPage "data.xsp", so wäre die URL:
http://localhost/Test1.nsf/data.xsp/companies

Die URL kann direkt über den Browser aufgerufen werden (impliziert Request-Methode GET) und die Einträge in der Ansicht sollten im JSON Format angezeigt werden.

Für diesen Zweck und zum weiteren schnellen Testen der API gibt es ein schönes Firefox Add-on mit dem Namen RESTClient. Damit lassen sich benutzerdefinierte Requests erstellen durch Angabe von HTTP-Methode, URL, Request Header und Request Body. Nach dem Senden der Anfrage wird die Antwort vom Server angezeigt.

Der folgende Screenshot zeigt die Antwort für den View Service "companies" im RESTClient:
A picture named M4



In der Antwort sind JSON-Eigenschaften mit einem '@' am Anfang enthalten. Diese markieren Systemspalten (nicht-benutzerdefinierte Spalten).
Die verschiedenen Datentypen werden in verschiedenen Formaten dargestellt, z.B. werden Strings in Anführungszeichen eingeschlossen, Zahlen nicht.
Eine detaillierte Beschreibung über diese und weitere Formate ist in der Dokumentation zu finden (Datei "DominoDataServiceDoc.zip" im Extension Library Download).


Arbeiten mit Dokumenten
Um ein API für einzelne Dokumente zur Verfügung zu stellen, muss ein zweites REST Service Control zu der bestehenden XPage hinzugefügt werden. Diesmal wird die "pathInfo"-Eigenschaft entsprechend dem Zugriff auf ein einzelnen Firmendokument benannt, z.B. "company". Der konkrete Service ist der Document Service (xe:documentJsonService):

A picture named M5



Die folgenden Eigenschaften sind gesetzt:
  • compact: Bei "true" enthält die Ausgabe keine nicht sichtbaren Zeichen.
  • defaultItems: Bei "true" werden alle Items sowie einige Metainformationen in die Ausgabe aufgenommen.
  • formName: Name der Maske, die zum Erstellen von Dokumenten verwendet werden soll.

Um den neuen Service zu Testen lässt sich wieder der RESTClient oder direkt der Browser verwenden (die UNID kann aus der View Service Antwort kopiert werden):
http://localhost/Test1.nsf/data.xsp/company/unid/56A63CD8312606F8C1257A54004009DD

Das Ergebnis sollte nun alle Felder des Dokuments enthalten, sowie einige Metainformationen (z.B. @unid, @form, $UpdatedBy).

Der nächste Schritt besteht im Aktualisieren eines bestehenden Dokuments. Aktualisieren wird für gewöhnlich über die HTTP-Methode PUT durchgeführt. Die Extension Library Implementierung macht hier noch eine weitere Unterscheidung: Die PUT-Methode wird zum Ersetzen des bestehenden Dokumenteninhalts mit den Daten im Request verwendet, wobei vorheriger Inhalt verworfen wird. Das Dokument wird anschließend genau die Daten enthalten, die im Request gesendet wurden.
Aber in den meisten Fällen wird man vermutlich nur einige Items ändern wollen und den Rest des Inhalts unberührt lassen. Dies wird in der Extension Library über eine weitere HTTP-Methode "PATCH" realisiert.

An diesem Punkt ist es erwähnenswert, dass der Domino Server in der Voreinstellung nur die Mehtoden GET und POST unterstützt. Die weiteren Methoden zu erlauben ist eine Einstellungssache in einem Internet Site Dokument, allerdings gibt es noch einen alternativen Ansatz, der auch dann sehr nützlich ist, wenn auf Client-Seite keine PATCH Requests unterstützt werden:
Die HTTP-Methoden PUT, PATCH und DELETE können alternativ auch durch die POST-Methode ersetzt werden und ein zusätzlicher HTTP Header "X-HTTP-Method-Override" kann gesetzt werden, der dann die zu verwendende Methode spezifiziert.

Wie lässt sich also das Ändern eines Items in einem bestimmten Dokument mit Hilfe des RESTClient testen?

1. Setzen des "Method-Override" Header
Im RESTClient von der Titelleiste folgenden Punkt wählen: Headers -> Custom Header
Der folgende Dialog sollte wie folgt befüllt werden:
A picture named M6


2. Es gibt noch einen weiteren Header, der gesetzt werden muss. Ansonsten wird die Anfrage mit einem Fehler quittiert:
Es geht um den "Content Type" der Anfrage, der das JSON-Format angeben muss.
Header Name: Content-Type
Header Wert: application/json

3. Ein bestehendes Dokument per GET abrufen (nur um Daten zum Ändern zu haben).

4. Die Request-Methode auf POST ändern und die korrekte Angabe der Header prüfen (siehe auch folgender Screenshot).

5. Im Request Body die zu ändernden Daten angeben (im JSON Format).
A picture named M7



6. Per "Send" die Anfrage abschicken. Wenn es keine Fehlermeldung gibt, kann das Ergebnis mit einem erneutem GET überprüft werden.


Andere Operationen:
  • Erstellen eines neuen Dokuments: Setzen der HTTP-Methode auf POST (ohne X-HTTP-Method-Override Header)
  • Löschen eines Dokuments: Setzen der HTTP-Methode auf DELETE (oder Methode POST und X-HTTP-Method-Override Header auf DELETE)



Programmatisch die Funktion des Document Service erweitern
Wenn Sie einen Ansatzpunkt zur programmatischen Erweiterung der Request-Verarbeitung benötigen, besteht eine Möglichkeit darin die Dokumentenereignisse, wie "querySaveDocument" zu verwenden.
Auf diesem Weg können zusätzliche Aufgaben durchgeführt werden und Dokumenteninhalt geändert oder ergänzt werden.

Die folgende Liste bietet eine Übersicht über die Parameter der verschiedenen Methoden:
  • queryNewDocument: Keine Parameter
  • queryOpenDocument: Parameter 'id' (Typ String)
  • querySaveDocument: Parameter 'document' (Typ lotus.domino.Document)
  • queryDeleteDocument: Paramter 'id' (Typ String)
  • postNewDocument: Parameter 'document' (Typ lotus.domino.Document)
  • postOpenDocument: Parameter 'document' (Typ lotus.domino.Document)
  • postSaveDocument: Parameter 'document' (Typ lotus.domino.Document)
  • postDeleteDocument: Paramter 'id' (Typ String)

Wenn die Request-Verarbeitung abgebrochen werden soll, bieten alle Methoden, deren Name mit "query" beginnt, einen boolesche Rückgabewert. Wird 'false' zurückgegeben, so wird eine Exception geworfen und eine entsprechende Fehlernachricht wird zum Client gesendet. Wenn 'true' zurückgegeben wird, so wird die Verarbeitung fortgesetzt.

Für noch mehr Kontrolle über die Verarbeitung und die generierte Ausgabe gibt es außerdem die Möglichkeit, ein Custom Servlet zu schreiben. Wie das funktioniert wird Thema eines zukünftigen Blogeintrags sein.
Read full article |Kommentare deaktiviert für REST Services mit der XPages Extension Library
Tags: , ,
Categories: Allgemein

Verfolgung von offenen Aufgaben im Domino Designer

10. Februar 2012 Posted by Thomas Ladehoff

Über die Tasks View in Eclipse bzw. im Domino Designer lässt sich eine Übersicht über To-Dos anzeigen und schnell zu den entsprechenden Stellen im Code navigieren.
Der für Java-Klassen standardmäßig aktivierte Mechanismus zum Scannen der Quelldateien nach den beiden Tags "FIXME" und "TODO" in den Kommentaren lässt sich dabei auch für XPages nutzen. Nur das hier die XML-Kommentare verwendet werden.
Dies ermöglicht eine bequeme Übersicht über offene Implementierungsaufgaben bei der XPages-Entwicklung.


Voraussetzung für das Anzeigen der To-Dos ist die Aktivierung der entsprechenden Prüfung der XML-Dateien. Der Einstellungspunkt ist in den Designer-Einstellungen unter "General - Editors - Structured Text Editors - Task Tags" zu finden (Häckchen "Enable searching for Task Tags").


tasksview_demo_small.png

Quelle und weitere Infos: Using the Eclipse Tasks view to keep track of to-dos in XPages projects in Domino Designer
Read full article |Kommentare deaktiviert für Verfolgung von offenen Aufgaben im Domino Designer
Tags: ,
Categories: Allgemein

JDBC für Domino: neue Möglichkeiten

11. Januar 2012 Posted by Thomas Ladehoff

Das kürzlich auf OpenNTF vorgestellte Projekt "JDBC Access for IBM Lotus Domino" ermöglicht ab sofort den Zugriff auf Domino Daten bzw. NSF-Datenbanken für eine Vielzahl von externen Anwendungen, die JDBC unterstützen.
Dazu werden Notes Ansichten als relationale Datenbanktabellen interpretiert und dessen Daten zur Abfrage über SQL Queries bereitgestellt. Somit wird nicht nur die direkte Integration mit anderen Anwendungen möglich, wie beispielsweise Reporting Systemen, es bietet auch die Aggregation von Daten über mehrere Ansichten hinweg, die noch dazu aus verschiedenen Datenbanken von verschiedenen Servern stammen können (z.B. mittels der SQL Befehle "Join" oder "Union").
Welche Ansichten für den Zugriff über JDBC zur Verfügung stehen, wird über entsprechende Dateien in der über JDBC angesprochenen NSF definiert.

Das auch DomSQL genannte System bietet sich auch für die Verwendung innerhalb von XPage-basierten Domino Anwendungen an. Zum einen aufgrund der Datenintegration über verschiedene Ansichten, zum anderen wegen der hohen Performance: der Abruf von Daten über JDBC läuft bis zu vier mal schneller als bei Verwendung des Java ViewNavigator (Verwendung des C-API).

Voraussetzung für die Verwendung ist Lotus Domino 8.5.3, und bei Nutzung durch externe Anwendungen zusätzlich den OSGI Tasklet Service (Es gibt zwei Installationsvarianten für die Nutzung durch externe Anwendungen und für die Nutzung durch XPages) Die Installation ist in der Dokumentation beschrieben.

Weitere Informationen gibt es auf OpenNTF, unter anderem auch folgendes Video, das einen Überblick liefert.
Read full article |Kommentare deaktiviert für JDBC für Domino: neue Möglichkeiten
Tags: , ,
Categories: Allgemein

Neuerungen des Upgrade Pack 1 für Lotus Notes und Domino 8.5.3

20. Dezember 2011 Posted by Thomas Ladehoff

Mit dem am 14. Dezember erschienenden Upgrade Pack 1 für Lotus Domino, den Domino Designer und den Notes Client werden folgende Features hinzugefügt:
  • XPages Extension Library
    Die XPages Extension Library wurde jetzt integirert und wird damit seitens IBM supported. Sie beinhaltet eine Vielzahl von nützlichen XPages-Controls zur Entwicklung von Web- und mobilen Anwendungen.
  • Neue TeamRoom- und Discussion-Schablonen mit Unterstützung mobiler Geräte
  • Domino Access Services: stellt ein REST-basiertes API zum Zugriff auf Notes-Datenbanken zur Verfügung.

Die XPages Extension Library, die auch als Open Source Projekt in regelmäßig aktualisierten Versionen auf OpenNTF.org erscheint, enthält über 100 Elemente zur Gestaltung von XPage-basierten Web-Oberflächen. Insbesondere werden hier auch Controls zur Unterstützung von Smartphones zur Verfügung gestellt, was die schnelle Erstellung speziell auf mobile Geräte abgestimmter Web-Oberflächen ermöglicht (entsprechende Styles und Themes sind bereits enthalten).
Für den Domino Designer bietet das Upgrade Pack 1 entsprechende Oberflächenunterstützung der Extension Library Controls, wie von den Standard XPages Controls gewohnt.
Einige der Elemente aus der Extension Library:
  • Verschiedene Mobile Controls, wie z.B. Header, Outline und Tab Bar Controls (inklusive Styles für IPhone und Android)
  • Form Controls auf Dojo-Basis
    Zur Verfügung stehen neue Controls für Eingabemasken, wie z.B. Toggle Button, Number Spinner, verschiedene Slider Controls. Außerdem gibt es alle Standard-Controls als Dojo-Ausführung, die um zusätzliche Funktionalität ergänzt sind, wie z.B. eine Drop Down Box mit Client-seitigem Type-ahead.
  • Diverse Dojo Container und Layout Controls, z.B. Tab Container, Data Grids
  • Verschiedene modale Dialoge und Picklists, Popup-Dialoge und -Menüs
  • Application Layout Control zur zentralen Definition und Anpassbarkeit des Anwendungs-Layouts
  • TagCloud, Tooltip, Outline und viele weitere
Das Upgrade Pack 1 kann alternativ zur Extension Library Version von OpenNTF.org installiert werden. Eine ggf. vorhandene Version muss also vorher deinstalliert werden. Weitere Hinweise zur Installation gibt es auch in Installing and administering the XPages Extension Library.
Die neuen TeamRoom und Discussion-Schablonen verwenden die XPages Extension Library und können auch als Beispiele für die Entwicklung eigener Datenbanken z.B. für die Unterstützung mobiler Geräte herangezogen werden.
Eine ausführliche Beschreibung der Neuerungen ist hier zu finden.
Read full article |Kommentare deaktiviert für Neuerungen des Upgrade Pack 1 für Lotus Notes und Domino 8.5.3
Tags: , ,
Categories: Allgemein