Thursday, 19 September 2013

Although we just released soapgate Q! 4.5, release 5 is already well on the way...

Release 5 is all about RESTful services and JSON.

As a first step we will provide for (almost) all SOAP operations available so far the equivalent RESTful operation. As part of this development we decided to speak JSON only.

In version 5 the implementation will be a wrapper around the existing web services, so the performance gain of REST compared to SOAP will not be as great as it could be. However, release 6 will bring a complete overhaul of the underlying web service code, which will result in all service operations (RESTful and SOAP) to return JSON formatted data.

The following URLs are a sample on how the RESTful interface will work...

  1. dbViewEntries (which is the equivalent to dbView2XML)
  2. dbViewEntries with additional parameters (first 10 rows and the view entry number for paging)
  3. dbViewEntries with additional parameters (next 10 rows and the document UNID)
  4. dbColumnX
  5. dbLookupX

Wednesday, 18 September 2013

soapgate Q! 4.5 has been released 2 weeks ago...

and finally I find the time to talk about what has been achieved in this release. The following is an extract of the release document contained in the download...

Fixes first:

A multi-threading bug was reported to us, causing a Domino Server 8.5.3 (64bit Windows) to crash reproducibly when load testing (multiple concurrent calls of) the dbLookupX() and dbColumnX() web service operations. This is apparently an issue of the NotesViewEntry.ColumnValues() method that of course is used in both of the above web service operation. The issue is under investigation by IBM.

We have implemented some changes to work around the usage of the effected Lotus Script class and seemed to have solved it from a soapgate Q! point of view.

Another issue reported and fixed was a subscript out of range error when calling dbFTSearch() where the search criteria would result in no documents. 

Changes & New Features

We have been working on performance on the new version and as part of this we restructured the web services. Instead of a single web service containing all web service operations, we have split and grouped them. We now have following web services:
  • DominoUtilityWebServices
  • DominoAdminPWebServices
  • DominoDocumentsWebServices
  • DominoViewsFoldersWebServices
  • DominoAccessNABWebServices
Please note: some of the operations in the new web services have additional parameters. However, the operations in the old DominoUtilitiesWebservices are not affected. We kept it backwards compatible.

One of the new parameters is the CACHE parameter related to a new feature in Release 4.5, which is data caching. If the parameter is set to true, the computed return value (array) is cached in a Notes document. The caching follows following logik:
  1. If a previous query with the same parameters has been found in the cache, the data stored in the cache document is returned if it has not been expired yet (5 minutes; until release it is a fixed value).
  2. If no cache document for the same query has been found or it has been found, but was expired, a new cache document is created or the found one updated with the data of the current query.
Note: the cache document is only accessible for the authenticated user, who created it. For multi-user scenarios the cache will not work or will have very little impact respectively. The cache feature is useful in a very limited set of scenarios only. Read the release document for more details.

Following operations in DominoDocumentsWebServices have additional parameters:
  • dbSaveDocFields()
  • dbSaveProfileFields()
Both operations support now a two step operation: saving and reading. After completing the save operation, the dbReadDocFields() or dbReadProfileFields() operations are called respectively.

dbLookupX() and dbViewFTSearch() now support paging.

In previous release we used a Java URL request to get the Domino Server to render a Notes Richtext field to HTML. This required some Domino (security) settings in the server document to work, despite not being the best performing method. However, it delivered the so far best results from a fidelity point of view. 

In release 4.5 we managed to use the NotesDocument.ConvertToMime method. This is much faster and touch less from a configuration point of view. We had of course to add some tweaks to support inline images and attachments.  
We added a RESTFul service to the soapgateQ! database to provide some XML formatted information about the database itself and the environment it runs in. By default the service is available to public users. So no authentication is required.