Using JAX-RS inside NSF follow-up - Swagger UI

Today I returned from another great Engage conference. Going to conferences gives you some fresh ideas, energy from the peers and motivation for next work, but it also takes some energy due to travel. This time I also returned with a few tasks and having currently Friday afternoon I decided to start with an easy one, just publish something I had in my drawer for a while.

More than a year ago I blogged about the possibility of creating JAX-RS based REST services directly in NSF. I remember that  Per Henrik Lausten liked it at that time. He also immediately mentioned that Swagger UI would be nice too, but I was too busy then to follow up on this. In following months I needed it myself but I never published it. So, as promised to Per at Engage, here it is.

Swagger UI can be really nice to have for testing, but what's more important, you get OpenAPI specification, which you then can use to generate clients for your REST API. And all with close to no effort.

Here is how it looks ...

Here is a list of needed adjustments:

Upgraded libs and Swagger

To make it work, I had to update the Jackson libs and few supporting libraries. I'm not 100% sure if all are needed, but I normally just put there all libs that I get as Maven dependencies to be sure. Libs in the current version are from last August and I haven't tested this on Domino 10, so if you want to use it, you may want to check the latest versions and their compatibility.

Added OpenApiResource

Just added the resource to the existing wink_application file in my application.

io.swagger.v3.jaxrs2.integration.resources.OpenApiResource

Added some annotations

Just to show it works, I've added some extra annotations.

Added Swagger-UI to the app

I only copied the html version to WEB-INF folder. I also slightly modified the index.html file, so it finds openapi.json file generated in same nsf. Of course you can host it somewhere else and just point it to the url.

Adjusted the SwaggerConfiguration

This is probably the most tricky part. You need to have correct endpoint URLs generated in the openapi.json in order to work with the Try buttons. I think this can be also overridden in the UI, but it's always better to have it in the file directly, so also other tools work with that. I still don't consider this as the best solution as it's in the plugin, so server wide, but it gets the job done for now.

With all this in place, you can just happily keep adding JAX-RS annotated resources to your nsf and you'll get openapi.json/yaml files automatically. You can almost feel like working with some modern platform.

Get it here: https://bitbucket.org/pradnik/pristo_rest/src/master/ (and yes, I've added additional todo to add some free license statement to the repo too, but for that, I also have to change the sample db to non-IBM one).

If you want to have similar features directly in the product, please vote for https://domino.ideas.aha.io/ideas/DDXP-I-409

Steps into Microsoft Universe

In recent months I did more and more integrations with different Microsoft platforms, being it good old AD, but also its Azure sibling and Exchange or Office 365. I had to learn a lot long the way and  last week I had opportunity to attend The European SharePoint, Office 365 & Azure Conference to get better overview of the ecosystem and future directions.

Having almost 2 decades of experience with IBM collaboration tools, quite often fighting against solutions from Microsoft, this step was both sad and exciting. Sad in terms that when I started with IBM Domino, it probably had bigger market share in messaging than Microsoft and whole ecosystem was better at that time. Since then, many things changed and now Microsoft is not even mentioning IBM as competition at all. I'm not saying that there is no future for IBM collaboration tools, but market has moved on since last big updates were done to those platforms and I've never seen any big vendor to be good at caching up with the market. HCL may bring new life to Domino, but it'll be definitely different life than one that was based on messaging and integrated collaboration tools. It'll have to be more open to external world.

When I went to the conference I was worried that everything will be different, but at the end I haven't found many differences between Notes/Domino or in general IBM collaboration events and this one. Terminology is similar, emphasis on collaboration and community is also same, so at the end just the name of the vendor was different. Even many tools look the same. I still have hard time to distinguish between Slack, Teams and Watson Workspace at first sight.

I think I had quite good general knowledge of the ecosystem and I hoped to clarify several areas bit more before I jump in and finally implement something with all these tools. After the conference I primarily learned that there is really no best way to implement things and it all depends on requirements of your solution, so you have to choose wisely and learn along the way.

Cloud

All vendors have been pushing customers towards cloud in many years. I think they have now realized that companies that wanted to use cloud technologies in cloud by now and they have to focus more on those who don't want to have everything in cloud or simply can't. Microsoft is building new data centers around the world to bring its cloud closer to the customers (and data withing their countries which helps to solve several legal issues), but this is usually not enough. Many sessions talked about hybrid architectures and options to connect to on premises systems and data.

Creating link between cloud and on premises servers introduces new sets of problem, mostly caused by connectivity and latency. Of course there is solution for that - just get an Express route.

If you don't want to have data in Microsoft Cloud but still want to use cloud technologies, you can even buy Azure Stack appliance. I remember laughing many years ago when IBM announced Bluemix Local, or how was it called.

You still have to remember that there is no real cloud (only those in the sky). This is just someone else's computer. Having more data centers means also different capabilities as it's not possible to deliver all services to all of those at same time. Core services should be available everywhere, but if you start to use some special services, you may need to check first.

Designing solution for this ecosystem is not easy. There are many moving parts and now those parts can also run around the globe, which is great but also brings new challenges. One of them is pricing, because all these tools and services come with a price tag that can change based on sheer amount of parameters.

You can always just run a VM in Azure, but this is almost same like putting box to a hosting provider in 90s. Still valid for some scenarios, but vendors try to encourage you to build cloud-native apps, because once you tightly integrate with their services, it's hard to leave. It was hard to leave Windows platform in past and it will be similar if you build solution on Azure with Azure Functions or other server-less services. I'm not saying that it's bad as building solutions for Windows systems worked well and still works for many companies. If you don't want to take the risk you can just package everything as VMs or put it into containers.

Office 365

Office is not about spreadsheet and text editor anymore. Currently re-branded as Microsoft 365 it should provide a platform for productivity. Yes, as always there is risk of big brother having all your data or vendor lock-in, but it's this what made Apple so popular. Seamless integration of all devices on many levels. Apple was doing this from very beginning and it was one of biggest advantages compared to Microsoft. I think just people who use Microsoft platforms for 20-30 are used to old way of installing a boxe software and then have everything guaranteed until their machine died. This model is gone now and we get continuous updates of apps on our phones, so why not main machines.

Office 365 itself is built from many products and Microsoft is trying to consolidate the architecture and also technologies used to extend it. Teams being probable the newest kid on the block, it's used as example how tools can use other services. It fully integrates with Sharepoint Online for content sharing, allowing also OneNote integration. I like the flexibility, but it'll require some guidelines for users to not get lost. Having too many options and too complicated solutions was always one of biggest problems of Microsoft compared to Apple, so let's see if they can get also this right.

Currently one of new additions to Office 365 platform are Adaptive Cards. IBM tried to do same with Embedded Experience many years ago, so it's again familiar topic. In this case you can create actionable message that users can directly integrate with in Outlook, Teams and even Microsoft Windows tasks list. Do action right in context of message without need for switching. I liked the idea when IBM came with it and I still like it.

Graph

Microsoft Graph should be the single point of integration for all third-party tools that interact with Microsoft 365. It's now three years old and while it's still getting new and new features, there are many challenges. If you just keep adding stuff to something, it'll turn into a monster sooner or later. Microsoft needs to decide how to proceed with this as having just one official v1.0 version is not going to work for ever. 

From feature perspective Graph rarely provides all apis that we need, so we have to switch back to PowerShell for more complex operations. I still see Graph more like content manipulation api that full management api, similar to EWS. Microsoft is also slowly deprecating EWS and moving all available APIs to Graph, so I think this will be next big thing on Graph once it's available.

There are many SDKs and libraries to integrate with Microsoft Graph, but I highly recommend to try at least few requests directly to see the options. SDKs are quite often generated from the API definition xml, but still can miss some well hidden options.

Azure

I've already talked about cloud in general. If you start to work with Azure it's scary. If you open the portal there are many buttons and sections that you have no idea what they do, even worse clicking on anything can probably cost you money. 

I think it's similar as if you walk into a data-center for first time. With all those machines, wires, boxes, etc. around you, it's scary. And actually this is exactly what Azure portal gives you, access to whole data center in web ui. Nobody understands everything about every piece in data center, so just pick one box/topic and start learning. 

Azure is a platform or ecosystem, which is continually being developed. This means you can never know everything and there is no version tag on whole Azure, just on individual components. If you start to work with cloud, you buy yourself a ticket for continuous learning.

Technologies

This was first Microsoft event for me, but I was happy to see that most of the information that was new to me was presented in way that it was new to everyone. Primary focus of the conference was Sharepoint, so many people in the audience also just did first steps toward cloud and new technologies and patterns. Average age of attendees was probably close to my age, so it was different than when you go to Google or general modern dev event, where everyone looks like just getting his drivers license. We are all in enterprise collaboration business for some time and have great experience, we just have to make sure it works with new tool.

Quite often there is old way to do things, new way to do things and sometimes several other alternatives. There is no right way to do things, you have to choose wisely. Many products, sdks and tools have one version that's being deprecated and another version that's in preview (and doesn't support all features). We have seen similar situation with other vendors too, for example Salesforce has classic UI and new Lightning UI, both having cons and pros. This is result of more agile way of developing the solutions. Deliver quickly, make it available to users, gather feedback and get ready for next iteration. There are no boxed products anymore, just solutions. This works well for SaaS, but other types of solutions have to adapt too.

Here are some pick for technologies that make sense to learn more in Microsoft world

JavaScript

OK, it's a general must nowadays. If you want to do anything UI related, or some Node.JS server work, you have to use it. Even Office 365 productivity tools are now written in JavaScript to be able to work in both web and desktop UI.

TypeScript is well supported by Microsoft, so you may give it a try.

PowerShell

PowerShell will still be the tool for automated management of many Microsoft products. There are several non-PowerShell tools for several areas, but still if you need to do anything more complex, you have to do it with PowerShell. 

Newest PowerShell is running on top of .NET Core, so it's more portable but sometimes not compatible with cmdlets from original PowerShell.

C#

.NET Core and ASP.NET Core try to make C# development more fun again. Microsoft had to re-design .NET Framework to make it interesting to developers in comparison to Node.js, SpringBoot and other technologies that make it easy to develop portable apps, that also work well in containerized environments. My knowledge of C# is limited, so I can't really compare them, but sentiment of blog posts is positive, so just give it a try.

Running C# directly in Azure Function seems to be good and easy example of integration of C# code into cloud architecture. Something I have to try soon. 

Graph

REST APIs are everywhere, so if you figured out OAuth dance, you are ready to use Microsoft Graph.

Azure

Yes, the cloud thing. Just learn the basics first, so you are not scared to click some buttons in Azure portal UI. Get a dev tenant and start experimenting. There is no better way to learn this then building something. Books can give you good start, but probable they are old already when released.

Azure DevOps

Every platform needs some kind of automation, so this is topic that I want to explore to try native Azure pipelines and other tools, not just use Azure as deployment target.

Bots

AI and bots are everywhere. Similar to Adaptive cards mentioned earlier bots are way to provide new way to interact with software. In Microsoft world bots can even work together with adaptive cards.

Microsoft has own Luis.ai bot framework, but it seems to be similar to what other vendors are doing (for the basic stuff).

Learn

Coming from IBM Domino space where all documentation is probably from 2010, resources in Microsoft world are overwhelming. To mention few:

Microsoft Connect event (4th Dec - today as of writing) - https://www.microsoft.com/en-us/connectevent/ 

Microsoft Learn - https://docs.microsoft.com/en-us/learn/

Microsoft Professional Program - https://academy.microsoft.com/en-us/professional-program/

and of course general sites like https://dev.microsoft.com or https://itpro.microsoft.com . I still don't understand difference between developer and it professional. Probably there are no professional developers for Microsoft platforms, just hobbyists. It that case I'd stick to IT pro to pay my bills.

Conference and Venue

Everything was well organized and the venue was perfect fit for size of the conference. If I remember correctly there were around 1800 people and I haven't noticed any sessions to be too crowded or completely empty. Catering was great and there was enough good coffee for everyone.

In general I really liked Copenhagen. I even had some time for sightseeing on Monday, when the weather was perfect, and I definitely have to come back to see more.

Conclusion

Overall it was nice event and I've learned a lot. It wasn't that much about content, but about the vision and I have to admit I like what Microsoft presented. I even consider joining Insider programs and start to use more features of Windows 10. 

Real world is not so shiny as conference presentations, but as many sessions were given non-Microsoft people, they all admitted that nothing is perfect and you have to be ready for troubleshooting and continuous learning. 

Next year

Will I attend next year? I don't know. It'll depend on how much deep I get into this Microsoft ecosystem and how valuable the content will be for me. If I go it'll be more about connecting with the community, not just checking out how it looks.

Next conference will be in Prague, so no sightseeing for me, unless I take a role of a tour guide. 

Microsoft Word black box in numbering issue

This is awkward post, primarily to save the solution for future me. I have seen many people mentioning this problem over years and as I've struggled with it several times, I needed to find final and permanent solution.

All editions of Microsoft Word from time to time suffer from bug in numbering. Instead of a number, black box is displayed. Sometimes it happens right after document is opened, sometimes during editing. Probably some internal structure of document gets corrupted, so based on level of corruption, different fixes could help. Many of them are listed at https://answers.microsoft.com/en-us/office/forum/office_2010-word/ms-word-header-styles-are-showing-black-boxes/c427b21c-dcda-46ce-a506-b9a16c9f2f3f


I took different approach. Since docx is just standard zip package with xml files, I decided to try if I can fix it manually. And it worked.

When I extracted the docx, there was file called numbering.xml in word folder. When I examined that file, I found strange section in heading that was causing problems. This w:rPr tag wasn't present on any other of level definitions.

When I deleted that tag and re-packaged the docx file, all worked fine.

Now back to productive work, fingers crosses that the document will stay as is for now.

Engage 2018 / Domino App dev

After missing last year event, I’ve returned to Engage conference, which was this time on decks of SS Rotterdam (unsurprisingly in Rotterdam, Netherland). While many things were familiar, like smiling faces of people from ICS community from all over the world, many things were different this year. From personal perspective, biggest difference for me was that for first time I took my family with me. It was our first trip abroad with our one-year old daughter, along with the older one. This required some compromises, including staying quite far from the ship, which saved me from drinking too much beer at captain’s/conference bar, but also missing some small talk that goes along with it.

I haven’t written down any notes during the conference and every session added another piece to the puzzle of new ICS landscape that is just unveiling, so I hope I can describe what I think is current situation in community/ecosystem/partnerships, you name it.

Last event I’ve attended was Social Connections in Vienna last year. This was the event, where some rumors about offloading of Notes/Domino from IBM started to spread across the community and most of session at Engage tried to explain where we got so far. If I compare content that was presented at IBM Think this year, presentations at Engage moved roughly by 2 IBM years (using progress from last few years). This can be both good and scary for some, but we are getting to a point where partners will finally understand role of IBM and HCL in their partnership. Next step will be to explain it to existing customers, which is also something that marketing departments in both organizations are working on. Message wasn’t communicated straight at OGS but was given in content of sessions and also in one-to-one conversations.

OGS

Keynotes contained good balance of vision, roadmap update and entertainment. It set the stage for rest of conference. I expected more announcements during OGS, but these had to wait to individual sessions. Only official announcement was about Domino Applications on Cloud available from IBM Marketplace https://www.ibm.com/us-en/marketplace/domino-applications-on-cloud#product-header-top. Everyone was waiting for release date of V10 Domino version, which we didn’t get, but we got timeframe for invitation-only Beta 1 (June, subscribe to newsletter at https://www.ibm.com/collaboration/ibm-domino  if you want to be notified about invitations) and open Beta 2 (later this summer). Together with “Golden Ticket tours” to labs in July we should be able to get more information soon.

Domino and Cloud

This session directly followed OGS and was an eye opener for me and probably many other people. While expanding on topic of IBM Domino Apps on Cloud, second half of session was about HCL Domino offering for Cloud, running on Azure and Amazon cloud. So, if you don’t want to host your data on SoftLayer, you have a choice to ask HCL to host this for you on Azure/Amazon. Both use similar stack based on Docker, but in future there seems to be possibility of using different tools and actually providing different offerings by IBM and HCL. At this point we started to realize that HCL want to do more with Domino and can do more within legal boundaries of their contract with IBM. And more was coming.

Notes on iPad

Native Notes app for iPad was announced at Think and there were many demos of this during Engage. Currently it works only in online mode, but replication/offline capability is coming in next Betas. HCL Nomad (I hope I got the spelling right) will be offered probably directly by HCL, but IBM Notes/Domino customers will be entitled to use this in their V10 licenses.

Once iPad is done, next logical step is iPhone support, which has some challenges due to limited screen size. This may require additional tooling added to Domino Designer, which would allow easy reorganization of form elements for that screen size. This is still something that needs to be clarified as while sounding easy, it can bring nightmares if code reuse is not properly managed.
Next on the list is support for Android and later direct support for web browsers using WebGL and other cool technologies. This would effectively remove need for ICAA.

Domino and Node.js

Another announcement from IBM Think was addition of Node.js ecosystem to Domino, or vice versa. More details were shown at Engage, while biggest change for me was replacement of NRPC with gRPC as communication layer between Node module and Domino. This will still allow turning off HTTP task on Domino, but reduces requirements on client side, making it easier and more portable for deployment scenarios.

There were some performance stats shown during the session, but as it was first iteration I don’t want to jump to any conclusions. There is always a tradeoff between flexibility and performance, so I assume it will be slower than NRPC, but easier portability and consumption. Currently there is no plan to open this communication to third-party integration directly, but HCL may do this in future.

Whole idea of integration of Node and Domino could be quite easy if Domino is used just as CRUD data store, but in that case, Domino would be reduced to just storage level, with not much of added value. HCL is aware of it and their goal seems to be leveraging as much of possible from Domino apps using those APIs, including calendar and scheduling APIs in future.

To make this work nicely in secure way, there will be integrations to Passport and other IDM Node modules to handle authentication and LoopBack support for API definition and management. We’re yet to see in real world how complicated this will be to setup and manage.

Notes client updates

For V10 HCL already demoed some mail enhancements in previous webcasts, like forwarding messages as EML or deferring sending of a message. During sessions here, they also demoed revamped workspace with menu option to change background image, preference page for changing of some default colors in Notes client and some more tricks. I think HCL is going for some quick wins in this area as many of these changes were doable in current versions, but not easily accessible. This could also make some users a bit happier.

There will be some enhancements to LotusScript. Most notable for me is support for HTTP calls with focus on JSON data manipulation. There also will be new functions to leverage mobile device capabilities on iPad and other mobile devices like GPS location or camera access.

Domino updates

V10 Domino updates seem to be mostly related to automatic problem resolution and easier management of high-availability environments. This includes automatic matching of databases in a cluster, more robust of streaming cluster replication after crashes/restarts, new options to export performance data from Domino to reporting systems, etc. On other side some limits within NSF have been pushed to new levels, like database size to 256GB or document summary information to 65K. Interesting change is replacement of attachment parsers in full-text indexer with Apache Tika, which should provide better support for more file formats.

Some already announced features have been postponed to V11, including better Active Directory integration and Full-Text search indexer replacement by ElasticSearch or Solr. This will be implemented together with Domino Event Publisher (or whatever the name will be) that should allow anyone to subscribe to Domino Events and be notified about them in real time. As it’s V11 feature, we’ll have to wait for more details. Another change that may come in V11 is replacement of iNotes by Verse, but all functions will have to be ported to Verse before doing that.

No Code/Low Code

Another interesting session was about Low Code/No Code options for Domino. Notes started as Low Code solution and created whole ecosystem around it. Keeping the balance and different tooling for No Code/Low Code/High Code scenarios seems to be on HCL radar as market for such solutions that allow “citizen development” is still growing and we all know that this was market that Notes used to dominate in past.

Challenge is to do this right. There is high risk that attempt to make everyone happy will result in something that will make nobody happy (and we have seen some low code attempts like composite apps in past that failed terribly). To embrace these different levels of tooling would require more stable implementation of code sharing and versioning than we have now and probably also completely different tools, not just different perspective in Domino Designer.

HCL is currently even playing with an idea to completely kill Domino Designer and replace it with Visual Studio plugin (not Visual Studio Code to be clear).

There was even Lotus Workflow mentioned during the session, which was first time in probably 10 years when I heard that product name from an IBMer.

HCL Places

This was probably the most controversial announcement of whole Engage. It was kind of a bomb that Jason Gary dropped not just on the audience but also HCL team (not sure about IBM on this one, but I guess some people there are still scratching their heads). It should be a desktop app that will use Domino infrastructure to provide activity stream like interface for communication, allow AI integration, support audio/video messaging and still open Notes apps. All on-premises.

At first it just remined me of IBM Workplace, yet another client that had to die, but after some thinking it started to make more sense as it gives answer to Why? question that HCL developers may ask around improving Domino/Notes platform. Honestly, I think that one of the reasons why we haven’t seen any updated in Domino in past few years was that IBM killed all products that they could sell on top of it.

HCL Notes/Domino

Most important message that I take home from Engage is that HCL is allowed to do their own modification to Notes/Domino code stream, even their own products around it and they are not even afraid to build solutions that can be considered direct competitors to IBM offerings.

Domino was for long time just enhanced as messaging platform as IBM had this need internally, but with HCL running their production mails on Office365, I think we’ll see a shift towards more integrated solutions with bigger focus on apps, which is frankly currently more and more common situations at many customers as they also move their emails away.

Partners

Similar to position of HCL, traditional ICS partners have built solutions for other platforms, or even build solutions that directly compete with original IBM ideas. Best example of this for me was AppFusion Aloha that is evolution of their solution from providing integrations of external data into IBM Connections to complete product/platform that can create central location for employee engagement.

Connections/Sametime/…

There was so many sessions about Notes/Domino that I couldn’t attend any session about other products. There wasn’t much new about Connections Pink and since the man in pink suite is now on HCL side working on yellow products, I can understand some challenges on IBM side.

For Sametime, IBM Mobile Connect, Wispr and probably bunch of other products that were moved to HCL, there should be dedicated teams working on those. Currently whole engineering organization around those products has roughly 420 people with 70 new open positions (probably mostly for new cool projects like Places or Low code tooling). I don’t know exact structure of HCL engineering around these products and to be hones I didn’t even pay attention when job titles were mentioned during sessions, because in past at IBM these usually changed till next event. Maybe this will be more stable at HCL and once we get first V10 releases out, we’ll know more about allocations and priorities for individual products.

More information to come

There weren’t typical IBM disclaimers at beginning of each session or in slides about confidentiality and subject to change notes, so I assume slides will be posted online. Also, HCL tries to do things differently with playbacks open to external partners and different communication channels used during whole development process. I was never part of IBM Design Partner program, so I can’t compare old processes with new model, but I think at the end this will be always about people who are responsible for the communication and their willingness for information sharing.

HCL also announced that important customers can get direct access to assigned technical expert from labs to discuss the strategy, planning or current issues (not replacement of PMRs). This could open to partners too in future, but currently it’s just for customers.

Where does this leave us?

HCL tried to demonstrate that they have a vision for Domino ecosystem. Many things are in early stage, just on Powerpoint slides or on Jason’s Mac, but at least they were told out loud and clear. Now they have to show if they are able to deliver on these promises/ideas.

App dev strategy could be probably simplified to couple ideas:
• Support On-premises deployment but allow easy move to cloud when possible. Provide added value in the cloud
• Open Domino app ecosystem to developers from Node.js world, open Node.js world to Domino developers
• Improve the tooling for low-code development, while keeping it possible to enhance the app with more complex code
• Use all previous points to build HCL Places client that will eventually run on all platforms (and replaces Eclipse Notes client)

There were many topics there were not mentioned that much anymore. One of them was XPages, that probably got last feature updates in FP10. I don’t see it as a priority anymore. With focus on open source software, we may get to the point (finally) when the runtime is pushed to OpenNTF, but I think there will be parts of new code committed first.

It’s hard to make any business decision based on information that we got. For existing development projects, nothing changes until V10 is shipped, or some stable beta with Node.js is out. For new projects, I wouldn’t probably start new project on Domino now, unless it’s a Notes client app for existing customer. There are many technologies that were mentioned over and over like React.js, Vue.js, Angular, Electron, PWA, so there are things to learn until Domino V10 matures enough to be used as backend for such app.

Wrap up

There was more valuable content than I expected and ICS (or whatever the community name will be now) has many topics to discuss. We should see by end on 2018 what HCL is able to deliver and we should see even more in 2019 with V11 release.

The conference overall was great. Theo knows how to impress attendees and I think I ran out superlatives that I can use to describe events that are organized by Engage team. I can’t wait to see what’s coming in 2019. I have some ideas, but I think organizing conference on the Moon or Mars will take few more years to put together, but if someone is able to do this, it’s Theo.
Thank you all for great time.

Using JAX-RS inside NSF

Last week Christian Güdemann published new release of SmartNSF on OpenNTF that contains cool new feature that Christian tweeted before. With new CUSTOM strategy it allows direct execution
of Java code from REST API defined in router configuration. It's even better than it sounds as it initializes facesContext and XPages application if needed, so even access to beans works.

I needed to start to build new REST APIs for few databases, so I decided to test new SmartNSF option and also other available options for REST APIs on Domino (there are several, check references at the end for more info). Since CUSTOM strategy requires dependency on SmatNSF in NSF project and also implementation of CustomRestHandler interface, it'd force me to do more changes in my code that I wanted to. If I need to change my code, why not adjust it for JAX-RS spec anyway.

Existing Domino JAX-RS options had to packaged as plugins, which make it hard to call code that is currently in NSF. I could make it work using pieces from SmartNSF, more classloading hacks and java reflection, but calling all code using reflection isn't best for development productivity. This way I was able to build JAX-RS API on top of existing NSF without changing anything in NSF itself, which would be perfect for my current use case, but I didn't like it.

I decided to take different approach. Use code from SmartNSF to take care of facesContext initialization and create XSP library that would allow direct usage of JAX-RS in NSF. ExtLib already contains AbstractRestServlet that wraps Wink implementation that is available on Domino for long time,  so at the end this solution required far less code than I expected.

Using com.ibm.xsp.adpater.servletFactory I was able to register own factory that takes care of new servlet creation for each servlet/nsf.

This factory also passes properties map to the servlet, so it knows where to look for Wink configuration and JAX-RS resources/providers.

Those paths are evaluated using module classloader, so it looks for files inside NSF.

CustomWinkServlet then just overrides getContextClassLoader method to point it to module classloader and takes care of facesContext and app initialization if needed.

I experienced issues with SessionAsSigner access, which I need for some configuration loading, so I had to move super.doInit() call to first doService call. Problem is that if something is loaded form NSF using module classloader when NotesContext doesn't have current session assigned or first resource is not a class (at least I think), it's not possible to get sessionAsSigner after that point. I got around by loading plugin.Activator first, which I know that should exist in any NSF.

With this infrastructure in place, wrapped as XSP library and installed on my server and Designer, I'm able to call existing XPages/Java code, including existing beans. For example:

For automated mapping of JSON data I included Jackson mapper in my plugin, so it can be just registered in wink.application along with resources.

In wink.properties I kept wink.defaultUrisRelative=false which was mentioned od Jesse's blog, but I really don't know if it has to be there. I'll have to test it. 

That's all what needs to be done. Now I can just access my new REST services: e.g.

or

If you want to try it yourself, sample database also contains showCounter.xsp that displays value from appBean, which is a proof that there is no secret double-life, which may happen when you use different approach for class loading. 

Now I can just wrap existing model and controller classes with JAX-RS annotations or thin wrapper layer when needed, so I can easily use same code from XPages and REST API. 

Source code is available on Bitbucket https://bitbucket.org/pradnik/pristo_rest .

I can imagine that combining this approach with OpenNTF API can make creation of JAX-RS services quite easy as ODA wrappers already take care for mapping proprietary Notes structures to standard Java classes. This is something to try next. 

Happy coding

Resources

Many good articles, series, sagas and samples were published around Domino and REST topics. Here is list of those that I know of:

SmartNSF - https://www.openntf.org/main.nsf/project.xsp?r=project/SmartNSF

Paul Withers- http://www.intec.co.uk/from-xpages-to-web-app-part-sixteen-osgi-jax-rs-rest-access-with-oda-revisited/

Jesse Gallagher - https://frostillic.us/blog/posts/87267DB72A55133F85257E380073495F

Sedar Basegmex - https://github.com/sbasegmez/RestAssuredDemo

Sven Hasselbach - http://hasselba.ch/blog/?p=2413

Toby Samples - https://tobysamples.wordpress.com/2015/07/09/jax-rs-or-the-way-to-do-rest-in-domino-part-4/

Eric McCormick - https://edm00se.io/servlet-series/

Extension Library REST Services - https://www.openntf.org/Projects/pmt.nsf/36B7CD129ED7357A86257AC6005523E7/$file/Extension%20Library%20REST%20Services.pdf

My presentation from SUTOL 2016 - Automation is developer's friend

Last week I had a session at Sutol conference about automation for developers. It covered several samples, where I started with Reat.js front-end app, stored it in Domino nsf database and later did also complete build on Jenkins server with Selenium tests.

It was a lot of fun to put this together and even more fun, as always, was to meet all those great people from ICS (or should I call it Watson Workplace now?) community.

Sutol 2016 - Automation is developer's friend from mpradny

Repository that I used for the demo is at Bitbucket.org - https://bitbucket.org/pradnik/todoapp_full/branch/develop . If you want to try it, you need to adjust some hardcoded values as I didn't make this build parameterized and it also depends on my Jenkins configuration. Job itself that I used was simple Pipeline from SCM, just with repo address.

Let me know if you want to try it and get stuck.

Many thanks to all sponsors,  organizers and attendees, who made SUTOL 2016 great event. 

SUTOL conference 2016

It became a tradition that every autumn SUTOL organize technical conference that focuses on topics around IBM ICS portfolio. After successful switch to English as primary language last year, this year the event will be extended to 1.5 days.

Event will take place at PARKHOTEL Praha on 10th and 11th November.

More details are at conference site 8th SUTOL Technical Conference. Registration will open soon.

Two day program of conference should give more room for attendee interaction and community discussion. We hope that more international attendees will find their way to Prague as autumn is really nice time to visit. Weather is usually still warm and it's less crowded than during summer season.

If you need any reason, why you should attend, let me know. Call for abstracts is open till 9th October and sponsors are also welcomed.

See you in Prague.