Mindoo Blog Cutting edge technologies - About Java, Lotus Notes and iPhone http://www.mindoo.de/web/blog.nsf/ en-us Sat, 30 Jan 2010 15:43:12 +0200 LS10 session sample #1: Notes Bookmark tools Sat, 30 Jan 2010 15:43:12 +0200 http://www.mindoo.com/web/blog.nsf/dx/30.01.2010154312KLEKA4.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/30.01.2010154312KLEKA4.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/30.01.2010154312KLEKA4.htm Lotusphere session about the Java APIs of Lotus Notes 8.5.1. And it's already the first one that we did not  actually show at Lotusphere, because we ran out of session time in our rehearsals and felt the need to reduce the amount of live demos.

The sample plugin is called "com.mindoo.bookmarktools". It adds two actions to the Open List of Lotus Notes:

Image:LS10 session sample #1: Notes Bookmark tools

Locate on workspace
This action uses the methods NotesUIWorkspace.addDatabase(NotesDatabaseData) of the new UI API, but instead of adding databases to the client's workspace, it actually only leverages the fact that addDatabase selects already existing databases and opens the right workspace tab.
As you may know, we are the developers of the MindPlan application (mindmapping and project management based on Lotus Notes). That's why my Open List looks like this when I'm searching for the keyword "mindplan" in my bookmarks:

Image:LS10 session sample #1: Notes Bookmark tools

Sometimes you want to know where a specific database is located on your workspace. One way is to open the database in the client and then switch to the workspace, where in most cases the right database chicklet is selected. That takes a lot of time in case the database needs to be loaded from a server. And sometimes opening the database does not really help to find it on the workspace, for example if the database opens a frameset that displays a view of your mail database. In that case, it's the mail database that is selected on the workspace, not the database with the frameset.

This new action helps in this case.

Open as workspace
The second action "Open as workspace" is something that you might know from older Notes Clients, e.g. from version R7. You could right click on a bookmark and select "Open as workspace". This would open a new tab that displays the bookmark folder content as chicklets like this:

Image:LS10 session sample #1: Notes Bookmark tools

Well, although this feature has not been officially implemented in the 8.x Standard Client (the was some discussion whether it should return in 8.5.2, but IBM decided to keep it out of the Standard Client), there is a way to open the workspace view for a bookmark folder.

Actually, it's pretty simple:
You may know that the Notes URL "notes:///ClientBookmark?OpenWorkspace" opens the normal workspace tab.
All you have to do is add a query parameter "id" to that URL: "notes:///ClientBookmark?OpenWorkspace&id=0". That ID is the internal bookmark folder id. The id 0 tells the workspace viewpart to display the first level of your open list (e.g. with your mail, calendar and a chicklet to start Domino Designer).
I haven't found out so far where the other id's come from (just checked the design of the bookmark.nsf, but it's no obvious ID of the folders design elements). But by using some internal Notes functions, we are able to grab the folder id when you right click on an Open List entry and launch the corresponding Notes URL.

So, what to do with this second action? I don't know. :-)
My first thought was to use this special Notes URL in a Composite Application, something like my personal start page for the Notes Client. You can for example use the Notes Document Container to display this URL and send URL changes to the "SetNotesDocumentURL" action to switch between several workspace folders. In my first tests, quickly changing this URL did not appear very stable (the client crashed) and I did not look into this any further.

Anyway, here are the source code for this sample and an update site for the installation (please refer to this article if you don't know how to install from an update site). ]]> http://www.mindoo.com/web/blog.nsf/dxcomments/30.01.2010154312KLEKA4.htm http://www.mindoo.com/web/blog.nsf/dx/30.01.2010154312KLEKA4.htm?opendocument&comments I will be presenting a session about the new Java APIs of Lotus Notes 8.5.1 at the German Entwicklercamp conference (Developer camp) Thu, 28 Jan 2010 07:30:23 +0200 http://www.mindoo.com/web/blog.nsf/dx/28.01.2010073023KLE9N3.htm Entwicklercamp 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/28.01.2010073023KLE9N3.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/28.01.2010073023KLE9N3.htm The topic is Add-ons for Notes Client/Domino Designer based on new Java APIs of Lotus Notes 8.5.1 (track 4, session 5 in the session list).
It's similar to our Lotusphere session, so if you missed it at Lotusphere, make sure to not miss it again. :-)

The Entwicklercamp is an annual conference taking place from 8th to 10th of March in Gelsenkirchen, Germany, with a well known list of both national and international speakers and a lot of high-quality developer sessions.
You can find more information on the Entwicklercamp website. Unfortunately it's only available in German language, but maybe Google translator will help you out if your German needs some training. ]]> http://www.mindoo.com/web/blog.nsf/dxcomments/28.01.2010073023KLE9N3.htm http://www.mindoo.com/web/blog.nsf/dx/28.01.2010073023KLE9N3.htm?opendocument&comments Our Lotusphere 2010 slides: BP203 - Leverage the New Java APIs in IBM Lotus Notes 8.5.1! Mon, 25 Jan 2010 00:41:24 +0200 http://www.mindoo.com/web/blog.nsf/dx/25.01.2010004124KLEVSF.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/25.01.2010004124KLEVSF.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/25.01.2010004124KLEVSF.htm All the feedback evaluations where either "Excellent" or "Good" and in addition, we also got personal feedback from 4-5 participants (even in the bus to the Hollywood studios on Wednesday) who especially liked the fact that we showed so many demos.

Well, to be honest, we even planned and developed more demos than we actually could show. We decided to remove some of them when we were doing a test run in the hotel room and easily exceeded the session limit of 60 minutes. :-)
If you look at the original BP203 slides that we submitted back in December and compare them to the presented slides, you will notice the missing pieces.

Since removing some of the demos was a last minute decision, all of them were already developed and running. So we plan to publish them in this blog in the next few weeks. Simply publishing the code would not help you much to learn about the Eclipse/Expeditor platform. That's why we will explain them in detail, each demo in its own blog article.

Let's start this demo article series with the session slides. Click on the image to download the PDF file:

Image:Our Lotusphere 2010 slides: BP203 - Leverage the New Java APIs in IBM Lotus Notes 8.5.1!


]]> http://www.mindoo.com/web/blog.nsf/dxcomments/25.01.2010004124KLEVSF.htm http://www.mindoo.com/web/blog.nsf/dx/25.01.2010004124KLEVSF.htm?opendocument&comments Our LS10 session offering on Wednesday: BP203 - new Java APIs in 8.5.1 with up to 10 demos, 2 undocumented Notes functions and Lotusscript like you have never seen it before Wed, 20 Jan 2010 00:26:26 -0400 http://www.mindoo.com/web/blog.nsf/dx/20.01.2010002624KLE8E3.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/20.01.2010002624KLE8E3.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/20.01.2010002624KLE8E3.htm Instead of showing too many technical details, our plan is to focus on real-life scenarios for the new APIs.

We have created a collection of up to 10 demos for both APIs, including
  • a universal help system for the Notes sidebar that provides information for the current database, form and field
  • an integration of Mikkel Heisterberg's LotusScript.doc into Domino Designer
  • an alternative picture based address selection dialog for emails that can be used without modifying the mail template

and we'll demonstrate ways how LotusScript code can communicate with the Eclipse framework to leverage the new API functionality as well.
This will include an application that uses multithreaded LotusScript - a new technology to move your long running LotusScript tasks into the background in order to make your Notes applications snappier.

Come and join us on Wednesday from 3:00pm - 4:00pm in DL S. Hemisphere III !

And please also join us on Thursday from 7:00am - 8:00am in SW Toucan 1 to share our experiences with Application Architecture based on Composite Application (BOF206).
]]> http://www.mindoo.com/web/blog.nsf/dxcomments/20.01.2010002624KLE8E3.htm http://www.mindoo.com/web/blog.nsf/dx/20.01.2010002624KLE8E3.htm?opendocument&comments Lotusphere announcement: LS2Eclipse - Leverage Eclipse/Expeditor features in your Lotusscript code! Mon, 11 Jan 2010 13:53:17 +0200 http://www.mindoo.com/web/blog.nsf/dx/11.01.2010135317KLEH5D.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/11.01.2010135317KLEH5D.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/11.01.2010135317KLEH5D.htm
  • You have Notes applications and want to bring them to the 21st century without rewriting everything in Java/JavaScript?
  • Your users often sit at their desk waiting for your Notes application because of a long running Lotusscript operation?
  • Composite Application technology looks interesting, but the Lotusscript APIs are not dynamic / powerful enough?
  • As a Lotusscript developer, you always hated it to hear those Java guys saying "That's easy. All you have to do is call this Eclipse API..." :-)
    • During our own Notes/Domino development in the past years, we often needed Eclipse API functionality in places where it was not available, like a classic view action, a form or an agent.
    New features always got added to the "outside world", the Eclipse/Expeditor framework, but the classic Notes client and the Lotusscript language nearly stayed the same over the years.
    While Java development for Eclipse/Expeditor has many advantages compared to classic form/view development of Lotus Notes, it surely makes development more complex and you loose the rapid application development approach that Lotus Notes made so successful.
    In addition, long-time Notes users have an existing code base of thousands of lines of code, that they cannot simply rewrite in Java/JavaScript to create a new Java UI or XPages based application.


    We think that there is a missing piece between classic Notes and the Expeditor framework of Lotus Notes R8.x. This is our main use case for Mindoo LS2Eclipse.

    Mindoo LS2Eclipse is a bridging technology that makes Eclipse APIs accessible from Lotusscript code.

    The following image is a rough overview of the LS2Eclipse architecture:

    Image:Lotusphere announcement: LS2Eclipse - Leverage Eclipse/Expeditor features in your Lotusscript code!

    The installation kit contains an Eclipse plugin (packaged as a widget for easy deployment) and a set of Lotusscript libraries.
    Those libraries with a rich set of about 50 object-oriented Lotusscript classes give you access to many powerful Eclipse features, divided into the following 7 areas:

    JobTools
    The JobTools area is a key feature of the LS2Eclipse API. It is the key to running your application code in multiple threads, thus making it possible to keep the user interface responsive even if a long-running operation (e.g. storing an email in a CRM system on a Domino server) is active.
    Your Lotusscript code runs as a so called Eclipse Job, a background process that can optionally display a progress dialog with status/progress information.

    Feature overview:
    • Bridge between the Eclipse job framework and Notes agents
    • schedule the execution of an agent as an Eclipse background job
    • pass parameters to the job
    • jobs can report progress and can be cancelled on user request
    • Notes UI is responsive when job is running, job may change the UI during execution (e.g. to present the result)
    PlatformUI
    The PlatformUI area let's you read and interact with the Eclipse workbench, which is the graphical framework that is displaying the Lotus Notes client.

    Feature overview:
    • Read the structure of open windows, tabs and their contents (Eclipse views)
    • focus tabs, show/hide/minimize/maximize views
    • Access the side shelf, show/hide shelf views and toggle the shelf between collapsed, thin and expanded
    • show text in the status bar of the Notes client and show message boxes (e.g. to display information from a background agent job)
    ComponentTools
    The ComponentTools contain a set of tool classes to make Composite Applications more dynamic.

    Feature overview:
    • call Composite Application actions of components manually without a CA wire
    • dynamically create and show content like Notes data or a web browser view
    • modify the properties of components
    • read and modify the structure of a Composite Application (component/page preferences)
    • toggle between CA pages in your code (e.g. to create a custom navigator)
    • locate open views in the workbench based on their internal ids
    NotesUITools
    This area contains features of the new Java UI API in Lotus Notes 8.5.1. With it you can interact with the Notes client user interface, even if your code is running in a background job, where the standard NotesUIWorkspace is not available. In addition, you are no longer restricted to the active area of the screen to read/write data from/to a view or a document.

    Feature overview:
    • gives you access to the Notes UI even when your code is running in a background job
    • get a NotesUIDocument/NotesUIView handle for any area (IWorkbenchPart) of the screen, not just the active one
    • modify the NotesUIDocument's content, read the current selection from a NotesUIView
    • activate a view/document in the current page
    PerspectiveTools
    In the Notes client, an Eclipse perspective is the content of a main tab. The perspective tools give you access to all registered tabs in the system and they even allow for the creation of completely new tab layouts.

    Feature overview
    • get list of registered Eclipse perspectives (IPerspectiveRegistry)
    • clone existing perspectives
    • create and display your own Eclipse tab layouts (IPerspectiveFactory/IPageLayout etc.) on the fly
    ProgramTools
    The program tools contain platform independent APIs to registered file extensions in the OS.

    Feature overview
    • find associated programs by file extension
    • get list of registered file extensions in the system
    • launch files and urls
    ExtensionRegistryTools
    Experts can use the ExtensionRegistryTools to add new Eclipse extensions to the IExtensionRegistry of the Eclipse framework.

    How does the code look like?

    We tried to name the Lotusscript objects similar to their corresponding Eclipse API objects. That way, you already know most of the important Eclipse APIs if you start coding in Java later on and searching for code snippets on the internet is made easier.
    To get a feeling for the API, here is a small code snippet:

    To create a new API connection, you use this syntax:

    Dim connection As EclipseConnection
    Set connection=EclipseConnectionManager.createConnection()

    To access the PlatformUI, type in this:

    Dim platfUI As PlatformUI
    Set platfUI=PlatformUIFactory.getInstance(connection)

    The IPartService is a class to get the currently active area (IWorkbenchPart) of the screen:

    Dim partService As IPartService
    Dim part As IWorkbenchPart
    Dim vpart as IViewPart
    Dim classes as EclipseAPIClasses
    Dim partTitle as String
    Dim partId as String
    Dim partSecondaryId as String

    Set classes=connection.EclipseAPIClasses 'helper to cast an object to another API object
    Set partService=platfUI.getWorkbench().getActiveWorkbenchWindow().getPartService()
    Set part=partService.getActivePart()
    If classes.IViewPart.isInstance(part) then
            'part is a IViewPart; this gives us additional properties
            Set vpart=classes.IViewPart.cast(part)
            partTitle=vpart.getTitle()        
            partId=vpart.getId()
            partSecondaryId=vpart.getViewSite().getSecondaryId()
    End If


    Where to get the API

    The API is feature complete, but we still have some documentation to write. For example, I'm currently working on a database with test cases that may be handy to learn about the new features.
    It currently contains the following 12 cases:
    • Case 1 - Workbench information
    • Case 2 - PartService, get information about the active viewpart
    • Case 3 - Viewparts in the current page
    • Case 4 - Schedule background agent jobs
    • Case 5 - Change the UIDocument in another viewpart
    • Case 6 - Get the selection from a Notes view in another viewpart
    • Case 7 - Create new NSF viewparts in the current page
    • Case 8 - Create new NSF viewparts in a different tab
    • Case 9 - Manually call actions of CA components (change content of a document container)
    • Case 10 - Create a new Eclipse perspective layout with placeholders for new views
    • Case 11 - Compare selected documents in a new Eclipse perspective
    • Case 12 - Toggle the sidebar mode between collapsed/expanded/thin
    If you are interested and will be attending Lotusphere next week, come to our session about the new Java APIs of Lotus Notes 8.5.1 (BP203) on Wednesday from 3:00 until 4:00 pm or wake up early on Thursday to join us in our birds-of-a-feature session about "Application Architecture based on Composite Application technology" (BOF206) from 7:00 until 8:00 am.

    I will post an info in this blog, when a trial version of LS2Eclipse is available.
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/11.01.2010135317KLEH5D.htm http://www.mindoo.com/web/blog.nsf/dx/11.01.2010135317KLEH5D.htm?opendocument&comments     Our Birds-of-a-Feather session has been selected by the Lotusphere attendees! Thu, 10 Dec 2009 16:32:54 +0200 http://www.mindoo.com/web/blog.nsf/dx/10.12.2009163254KLEL95.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/10.12.2009163254KLEL95.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/10.12.2009163254KLEL95.htm Our session is one of those that they would most like to see on the agenda.

    This is IBM's description for this kind of session:

    Audience: Any and all Lotusphere attendees
    Description: Come one, come all! Birds-of-a-Feather sessions are a popular feature of Lotusphere, bringing together communities and individuals with similar interests. These sessions are informal, interactive discussion groups for like-minded attendees to share ideas and experiences in an small group, open forum setting.


    And here is our session abstract:

    Application Architecture based on Composite Application technology


    Composite Application technology builds a bridge between several worlds. With it you can transfer information between programming languages like Java and Lotusscript, fill Symphony spreadsheets with the contents of a Notes view, sent commands to host applications and even automate Windows applications.
    With the introduction of XPages for the Notes client, CA technology gains additional momentum, because they are the way to go, if you need interaction between your XPages application and the surrounding Notes client platform.
    We would like to share our experiences with Composite Application technology and discuss how an application architecture based on Composite Application technology could look like if you start designing it from scratch.

    We are really looking forward to Lotusphere and are heavily working on cool demos for our session about the new Java API's of Lotus Notes 8.5.1. ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/10.12.2009163254KLEL95.htm http://www.mindoo.com/web/blog.nsf/dx/10.12.2009163254KLEL95.htm?opendocument&comments     One Lotusphere 2010 session approved! Tue, 17 Nov 2009 20:38:06 +0200 http://www.mindoo.com/web/blog.nsf/dx/17.11.2009203805KLER2D.htm Lotusphere 2010 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/17.11.2009203805KLER2D.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/17.11.2009203805KLER2D.htm The title is:

    Add-ons for Client/Designer leveraging new Java APIs of Lotus Notes 8.5.1


    This is really cool, because it's our favorite topic. Those new APIs can be used for many small useful Notes and DDE add-ons and I'm sure we will have some nice giveaways for the session.

    See you in Orlando!
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/17.11.2009203805KLER2D.htm http://www.mindoo.com/web/blog.nsf/dx/17.11.2009203805KLER2D.htm?opendocument&comments     XPages series #8: Dynamically creating the UI of an XPage in Java Tue, 10 Nov 2009 23:11:23 +0200 http://www.mindoo.com/web/blog.nsf/dx/10.11.2009231122KLEU27.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/10.11.2009231122KLEU27.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/10.11.2009231122KLEU27.htm XPages series is more or less a link to a great blog posting that was just published my Tommy Valand.

    It demonstrates how you can create a dynamic web user interface by leveraging JSF features in your XPages application.
    In his example, Tommy produces a data table UIComponent with a snippet of Java code that is executed with the click on a button.

    Image:XPages series #8: Dynamically creating the UI of an XPage in Java

    I'm currently working on something similar for a customer project, but unfortunately I cannot say much about technical details at the moment.
    Basically, it's about dynamic application UI creation based on an abstract UI description. The system produces a dual-output: it dynamically creates the UI of an XPage, but it also creates a Java UI (e.g. a set of Swing components) with a similar form layout.
    Write once, run anywhere. :-)

    The concept includes its own data layer that works independent from Lotus Notes and has some fancy features like transaction logging (even for storing in Lotus Notes databases).

    I recommend that you take a look at Tommys posting and start thinking about your personal use case for this. Anything is possible.

    In my next blog series posting I'm going to write about my own bean manager for managed beans that I needed as a workaround for security limitations when running an XPages application in the Lotus Notes client. ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/10.11.2009231122KLEU27.htm http://www.mindoo.com/web/blog.nsf/dx/10.11.2009231122KLEU27.htm?opendocument&comments     Today Mindoo joined IBM’s Design Partner program for Quickr 8.5 Wed, 4 Nov 2009 13:42:02 +0200 http://www.mindoo.com/web/blog.nsf/dx/04.11.2009134201KLEGWC.htm Quickr Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/04.11.2009134201KLEGWC.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/04.11.2009134201KLEGWC.htm
    We would like to thank IBM for letting us participate! ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/04.11.2009134201KLEGWC.htm http://www.mindoo.com/web/blog.nsf/dx/04.11.2009134201KLEGWC.htm?opendocument&comments     Speaking at Notesusertage 2009 (Notes user days, German conference) on the 5th of November - register until the 25th of October! Thu, 22 Oct 2009 21:49:23 +0200 http://www.mindoo.com/web/blog.nsf/dx/22.10.2009214922KLER9E.htm Notesusertage 2009 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/22.10.2009214922KLER9E.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/22.10.2009214922KLER9E.htm Haus Weilgut in a parallel customer track.
    The first one is a pretty large XPages application framework (about 10 Java projects combined into one NSF). Let's call it a "UI generator", but it's actually a lot more than that.
    The second application is a quite powerful relational reporting engine for Lotus Notes data. Something like "NotesSQL2". :-)

    The Notesusertage conference is an annual German Notes conference located in Karlsruhe, Germany.

    Registration is open until the 25th of October. Conference fee is 69 Euro.

    Here is the German conference description from the Notesusertage website:

    Warum in die Ferne schweifen, wo das Gute doch so nah.

    Erfahren Sie, wie Sie konsequent Ihre Lotus Notes- und Domino-Plattform im Unternehmen ausbauen und tauschen Sie sich mit Gleichgesinnten aus.

    Die Notes Usertage treffen den Nerv der Zeit:
    Anhand praktischer Beispiele aus großen und mittelständischen Unternehmen lernen Sie neue Erweiterungsmöglichkeiten kennen, mit denen Sie Investitionen in neue Systeme und Schnittstellen vermeiden. Dabei bringen Sie Ihre Infrastruktur auf den Stand, den die aktuelle Rechtslage erfordert.

    Mehrwert mit Lotus Notes, das bedeutet:
    • unternehmensweites CRM
    • Wissens- und Projektmanagement
    • wirtschaftliche und rechtskonforme Archivierung von E-Mails
    • Kopplung mit ERP-Systemen
    • Ressourcenplanung
    • Optimierung mit Blackberry
    • schneller Zugriff auf Informationen
    • Reporting, Business Intelligence
    • ... und vieles mehr!
    Neue Funktionen, Module und moderne Technologien machen Ihr Unternehmen leistungsfähiger und helfen Ihnen, vorhandene Ressourcen besser zu nutzen. ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/22.10.2009214922KLER9E.htm http://www.mindoo.com/web/blog.nsf/dx/22.10.2009214922KLER9E.htm?opendocument&comments     XPages series #7: Running under a restricted Java context - or: Why doesn’t my XPages application work in the Notes Client?! Wed, 21 Oct 2009 14:25:51 +0200 http://www.mindoo.com/web/blog.nsf/dx/21.10.2009142550KLEGL7.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/21.10.2009142550KLEGL7.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/21.10.2009142550KLEGL7.htm As long as they only contain program code in JavaScript and a few simple Java routines, you will probably have succeeded. Your application looks quite the same as on the web and you can now begin to tweak the UI with a client-specific theme and enhance the application features by integrating it into a Composite Application.

    Any visual issues?
    If there are any visual issues (for instance I heard about dojo dialog boxes not resizing as expected, but haven't tested yet), keep in mind that the 8.5.1 Notes Client uses Xulrunner version 1.8.1.3 to display the XPages, which is the render engine of Firefox 1.5 as far as I know. So make sure to have everything you do compatible with that "nearly recent" Firefox version. ;-)
    (the Xulrunner executable is located in the folder \framework\rcp\eclipse\plugins\com.ibm.rcp.xulrunner.runtime.win32.x86_6.2.1.20090925-1604\xulrunner)
    It should be possible to do that (1.5 was already quite powerful), although I'm a bit confused because this page says that the dijit widgets are only supported in Firefox 2+x. But I saw at least the dijit tabbedpane work without problems in one of my apps.

    Java execution errors?
    Let's say that you followed this blog series and did your homework. You have tried to use JSF managed beans in your application, understood the concept and like it.
    Well, then you may have already seen this Java exception thrown in a few methods, for example in those that call our JSF managed bean helper class:

    javax.faces.FacesException: java.lang.SecurityException: ECL Permission Denied
       com.sun.faces.application.ApplicationAssociate.createAndMaybeStoreManagedBeans(Unknown Source)
       com.sun.faces.el.VariableResolverImpl.resolveVariable(Unknown Source)
       com.ibm.xsp.el.VariableResolverImpl.resolveVariable(Unknown Source)
       com.sun.faces.el.impl.NamedValue.evaluate(Unknown Source)
       com.sun.faces.el.impl.ExpressionEvaluatorImpl.evaluate(Unknown Source)
       com.sun.faces.el.ValueBindingImpl.getValue(Unknown Source)
       com.sun.faces.el.ValueBindingImpl.getValue(Unknown Source)
       com.acme.tools.JSFUtil.getBindingValue(Unknown Source)

    When I first saw this, I yelled something comparable to "Interesting! How fascinating! A welcome challenge for me!". Ok, maybe less polite ;-).

    That was 2-3 days ago. Since then, I did some research and testing to find out what is causing this problem and how to deal with it.
    I'd like to share it with you.

    The Domino Server - a secure environment
    So far, we did our Xpages development on a Domino server. We were allowed to do this, because our administrator granted us developer rights on a database on the server, and he gave us the power to execute our code on that machine. He does not allow anybody to do this. He knows us and trusts us.

    Controlling access in the Notes Client
    It's a slightly different situation for the Notes client. A Notes user could download a Notes database with malicious code from anywhere on the internet.
    That's the reason why there is an Execution Control List (ECL) in the client to restrict what applications may do on the user's workstation. Critical operations like accessing the machine's filesystem need to be confirmed (trusted) by the user - and the administrator can prevent Notes users from easily trusting anyone.
    The ECL is not a new invention. It's been in the client for many years and controlled the program code of forms, views, agents and other design elements.

    For Eclipse plugins extending the Lotus Notes Standard client, there is no such thing as an ECL (because Eclipse does not have it), only the installation of plugins can be controlled by policy.
    This has produced a lot of discussion about the security of Eclipse plugins.

    Security for local Xpages
    For the first implementation of XPages in the Notes client, IBM chose a more conservative security model. The Java programming language has a built-in security system, called the SecurityManager, that IBM connected to the ECL system of Lotus Notes. Everything that is not connected to the ECL system of Lotus Notes, is considered insecure and is therefore denied.

    Java developers may already know the impact of the SecurityManager when they try to do restricted operations (like accessing files) in Java applets. They just don't work.

    So that's what happens behind the scenes in our method "JSFUtil.getBindingValue(String)". It calls JSF functions and deep in the calling tree, there is a restricted method and the JVM says "no".

    The good news
    The administrator does not have to worry about end users that download and open XPages applications from the web.

    The bad news
    The developers and ISVs have to worry about what their application code is allowed to do and how to deal with the restrictions.

    What is allowed?
    Here is a table with the available classes of allowed Java operations and their equivalent ECL levels in Notes 8.5.1:

    Java PermissionNote Client ECL Access (Workstation)
    java.util.PropertyPermissionEnvironment variables
    java.io.FilePermissionFile system
    java.net.SocketPermissionNetwork

    (plus using the Notes Java API)

    Calling a Java operation that needs one of these permissions results in a Notes ECL confirmation dialog if the XPage's signer is not trusted. Any other restricted Java operation that is not listed in the table will fail for Xpages in the Notes Client 8.5.1.

    What is not allowed?
    Ok, this is the "not so funny" part of this blog posting. I did a few tests. I don't have a complete list, but I have some of the things that hurt the most:
    • using java.net.URLConnection, e.g. to easily connect to a web server
    • XML parsing with javax.xml.parsers.DocumentBuilder
    • Loading Java resources with Class.getResourceAsStream()
    All three are prohibited because java.net.NetPermission is not connected to the ECL system.
    Regarding the URLConnection: Please note that you can use networking. I have a working demo of an XPages application in the client that downloads a HTML file from a web server (by using Java's Socket class and the HTTP protocol) and analyzes it in an XPages application in the client. Actually, at the moment, it's not 100% working any more, because I just upgraded to a new version of JTidy which now internally loads Java resources with Class.getResourceAsStream(). Ouch... ;-)

    Workaround for developers
    Add the grant command shown below to the java.policy file under the Notes directory and restart the client.

    grant {
         permission java.security.AllPermission;
    };

    This completely disables the security restrictions of the platform. That's why it's an extremely bad idea to do this on a user's machine. :-)
    But it makes it easy for you to work on your Java code and test it in the client.

    Workaround for customer installations
    This is not really a workaround. It's the only thing we have. ;-)

    You can put all your restricted code in a JAR file and store it in the jvm/lib/ext directory of the Notes Client. That code then has the right to run with a higher security level and may do the things that your XPages Java code is not allowed to.
    Please note that you need a special syntax in your code to ask Java for that higher privilege level:

    public class ExternalWorkaroundClass {
       public String tryWorkaround(final String anArgument) throws Exception {

           String result = AccessController.doPrivileged(
                   new PrivilegedExceptionAction() {
                       public String run() throws Exception {
                           String result=null;

                           //do some restricted operations here to compute result

                           return result,
                       }
                   }
           );
           return result;
       }

    How should I automatically deploy this to a few hundred customers???
    Don't ask me. Be creative. ;-). IBM dev is working on a better solution and more supported Java permissions in a future version (hopefully 8.5.2 or some kind of 8.5.1 fix pack).
    Looks like they thought that most of the XPages developers do not use those restricted (or any) Java classes at all. So the impact of this would not be too big.

    And they were probably right. But for us, this really hurts.

    What about managed Java beans?
    I guess the JSF method that produces the Java exception shown at the beginning of this article either wants to load the JSF configuration XML file faces-config.xml as a Java resource or it wants to parse it using the JVM's XML parser.
    But hey, remember I said something similar to "A welcome challenge for me!"? :-)

    I'm currently writing my own bean manager. The whole bean concept is about creating a bean, feeding it with default values and storing it in the right scope. Who needs the JSF bean manager for that? :-) ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/21.10.2009142550KLEGL7.htm http://www.mindoo.com/web/blog.nsf/dx/21.10.2009142550KLEGL7.htm?opendocument&comments     Notes 8.5.1: The new Java UI classes and Domino Designer extensibility API Sun, 11 Oct 2009 17:46:06 +0200 http://www.mindoo.com/web/blog.nsf/dx/11.10.2009174606KLELHE.htm Lotus Notes 8.5.1 Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/11.10.2009174606KLELHE.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/11.10.2009174606KLELHE.htm Disclaimer: IBM Lotus Notes/Domino 8.5.1 is prerelease code and there are no guarantees from IBM that the functionality presented or discussed will be in the final shipping product.


    I haven't read any blog articles yet about the new extensibility APIs that come with Lotus Notes 8.5.1. Since we participated in the discussion with IBM (at Lotusphere 2009 and later on in the Design Partner Program) about what needs to be part of a first official API version, I would like to give you some hints where to find these new APIs and what they are about.

    Two new extensibility APIs will ship with Lotus Notes 8.5.1:

    Domino Designer Extensibility API
    With this API, an experienced Eclipse Java developer is able to track the user's selection in DDE (e.g. the Note ID/Notes URL of the selected design elements) in order to apply his own design modifications (e.g. via DXL import) and let DDE catch up with the modified design elements afterwards.
    It contains functions to convert a standard Eclipse IProject into something called DesignerProject that provides additional information for a NSF database project in DDE. You get the basic NSF data like server/filepath/replica-id, some design related infos (template names, design hidden flag) and a few interaction methods, for example to open a database in DDE and to initialize/refresh the whole NSF project or single design elements in case you applied some changes to the backend Notes database.

    Notes Client Java UI API
    The Java UI API lets you get a handle on the currently opened UI document and UI view, called NotesUIDocument / NotesUIView:

    NotesUIWorkspace ws=new NotesUIWorkspace();
    NotesUIDocument uidoc=ws.getCurrentDocument();
    NotesUIView uiview=ws.getCurrentView();

    You do not have all the methods in Java yet that you know from the Lotusscript NotesUIDocument/NotesUIView, so don't expect too much for round nr 1. (But read on until the last paragraph to see why this is not a real problem)

    NotesUIDocument
    With the Java based NotesUIDocument you are able to modify fields in the backend document. It provides refresh methods to make those changes visible in the front end.
    Please note, that I said "modify fields", not "get the backend document". There are technical reasons (for example running in different threads and the Client's memory management) that make it impossible to get a full handle on the backend document, but the functionality of the API should be enough for most of the use cases.

    You can get information about the currently focused field (including tracking focus changes with a DocumentFieldListener), toggle edit mode on/off, cut/copy/paste/insert text in the UI and detect that a document has been modified.

    NotesUIView
    The NotesUIView class gives you access to the view's name/UNID/URL. There is a method to print the view.

    That not much for the NotesUIView, but by using the available Eclipse selection APIs you were already able to grab the selected documents in earlier Lotus Notes versions.

    NotesUIWorkspace
    In addition to the methods getCurrentDocument() and getCurrentView(), NotesUIWorkspace contains various methods to open Notes contents, like views, framesets or pages. There are also a few compose(...) methods that open a form to create a document in the Notes client. You can optionally specify a Document as an argument that contains fields that should be set as default field values in the form (this document can be a temporary document created with NotesUIWorkspace.getTemporaryDocument(Session)that is automatically deleted when the Notes client shuts down).
    NotesUIWorkspace.addDatabase(...) adds a database to the workspace of the Notes client.
    And finally, there is a NotesUIWorkspace.prompt(...) method that works like the corresponding method in Lotusscript. That means it displays different forms of selection dialogs with the style of the Notes client.

    Need more information?
    So, how do you know the exact syntax of the available classes and methods?
    You can find the complete Javadoc documentation for the two new APIs in the help system of the Lotus Notes client:

    Image:Notes 8.5.1: The new Java UI classes and Domino Designer extensibility API

    There is one more thing :-)
    Oh wait, I forgot one method. Actually, it's my favorit one.
    When we saw the first draft of the Java UI API at the end of last year, we thought of many things that we would like to add.
    But you know, you quickly realize that you can only concentrate on a few features or even a single one, that is the most important to you and needs to be available for round nr 1.

    Together with a few other design partners, we desperately asked/begged IBM to add one method, that is mission critical for the success of the API release.

    The basic question was: What would you do if a feature is not available in Java, but you know that it's there in Lotusscript? You write a Lotusscript agent and call it from Java.
    Something like

    Database db=session.getDatabase(server, filepath);
    Agent myAgent=db.getAgent("MyLotusscriptAgent");
    myAgent.run();

    That's nothing new. A standard function in the Notes Java API sind R5 or R6.

    Ever tried that with an agent that should do something in the UI, like changing a form's field values or open a selection dialog?
    It does not work.

    That's because Lotus Notes only executes that code in the backend, you do not have any UI access.

    Here is the solution:

    public void runAgent(NotesAgentData agentData, NotesDocumentDataCallback callback, boolean runOnUIContext)
    From the javadoc:
    Runs the agent represented by the agent data. Pass in false for runOnUIContext to run your agent on a temporary document. Pass in true for runOnUIContext to run your agent on the current selected document in the UI. Values added to the NotesAgentData object, using the addItem method, will be added to the temporary document. Also note with this method you can run an agent from one database on a completely different database. In other words, the agent you are running does not have to run on documents from the same database. While this gives the user more flexibility it also may break some assumptions of the agent, for example what fields are on the document.

    When running an agent on a temporary document it is recommended that you set the Target in the properties dialog of the agent to be 'None'. You can do this while editing the agent in Domino Designer. This allows you to run the agent without having anything selected in the UI. To access the temporary document from your agent, you can use Session.DocumentContext in LotusScript, or Session.getAgentContext().getDocumentContext() in Java. The note id of the temporary document is returned to you in the NotesDocumentDataCallback object.
    [...]
    Parameters:
    agentData - data about the agent to run
    callback - callback to run when agent is done running
    runOnUIContext - true to run the agent on the current UI context false to run the agent on the temporary document

    This new method is incredibly great.

    It means that you can put all the code that is missing in this first Java UI API release into a Lotusscript or formula agent and use NotesUIWorkspace.runAgent() to execute it -  in any database. And even better, there is a callback mechanism that you can use to get notified when the code is done to grab some results from a parameter document or the Notes.ini.


    Tomorrow is Notes 8.5.1 release day. Have fun playing with the new APIs!
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/11.10.2009174606KLELHE.htm http://www.mindoo.com/web/blog.nsf/dx/11.10.2009174606KLELHE.htm?opendocument&comments     XPages in the client: How to use XPages as components in Composite Applications Mon, 14 Sep 2009 17:55:08 +0200 http://www.mindoo.com/web/blog.nsf/dx/14.09.2009175508KLELNZ.htm Composite Application Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/14.09.2009175508KLELNZ.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/14.09.2009175508KLELNZ.htm Disclaimer: IBM Lotus Notes/Domino 8.5.1 is prerelease code and there are no guarantees from IBM that the functionality presented or discussed will be in the final shipping product.


    Today two interesting videos have been posted to the Domino Designer wiki that demonstrate how XPages in the Lotus Notes client 8.5.1 can be integrated with other components by using them as components of a Composite Application.

    Component definition for XPages
    The first video shows how to transform an XPage into a new design element type called Component, that can then be used in a Composite Application. For a Component, you can define your own properties in order to configure the referenced XPage for a specific use case.
    In the video, this is used to alter the theme of the XPage and to show and hide elements within the XPage's UI depending on the property value. By defining component properties, your XPages become much more reusable and configurable. The purpose is to reuse the same XPage in many different contexts (inside Composite Applications) without the need to change a line of code.

    Image:XPages in the client: How to use XPages as components in Composite Applications
    XPage of the discussion database as a component in a Composite Application (click to watch the video)


    Wiring XPages components to other components
    In the second video, the XPage is wired to a mail database component and a web browser component. They communicate in both directions by sending Composite Application properties:
    Clicking on links in the XPage changes the search query on the web and generates a new email with pre-filled fields. In the other direction, clicking on an email in the inbox opens the mail sender's article list in the XPage discussion database.

    Image:XPages in the client: How to use XPages as components in Composite Applications
    Composite Application of an XPage, a Notes Java view and a browser component (click to watch the video)

    The video contains pretty simple examples, but when you understand the idea behind the whole concept, a lot more can be achieved with this technology. It's a great opportunity to extend the functionality of "XPages in the client".
    In Lotus Notes 8.5.1, the pure XPages runtime will only provide basically the same as in the web browser. But by using Composite Application technology, you can easily add features to your application that are not yet available for XPages.

    Let's take a look at another use case:
    You could produce a formatted text in the code of your CRM XPages application (e.g. your own XML format from the user's selection) and publish it through a CA wire. Either you or any other developer can then build a CA component to receive and process this content.
    They could e.g. develop it in Lotusscript to produce some fancy Notes richtext output or write an Eclipse plugin in Java to automate the Symphony office suite that is build inside Lotus Notes to create a new document, like a letter or even a complete report spreadsheet.
    In this use case, the components that take care of the content output to richtext/Symphony, could also be hidden helper components without UI contribution to the Composite Application.

    Summary
    Although the first XPages implementation for the Lotus Notes client 8.5.1 is basically more or less a portable web application container, you can use Composite Application technology to add more functionality.

    The benefit of the Composite Application architecture is to mix a lot of technologies for the purpose of a business use case without the need to redevelop cross-technology interfaces over and over again. Composite Applications have a simple data exchange system: The CA components use simple strings to send and receive data to other components. Components are connected through so called Composite Application wires to exchange this data.

    Hopefully, the integration into the Notes client will be further improved in later Lotus Notes releases. The JSF technology that the XPages runtime is build upon, provides a technology called custom render kits. They can be used to create alternative output formats of a JSF application, e.g. native Java rendering in SWT or Swing or maybe solutions for mobile phone.
    Although developing a custom render kit is a lot of work, this might be a way to enrich the XPages experience with native controls (like Java views and the native Notes richtext editor) in a later Lotus Notes version. Another approach could be to extend the XULRunner that the XPages runtime uses in the client to render the UI.
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/14.09.2009175508KLELNZ.htm http://www.mindoo.com/web/blog.nsf/dx/14.09.2009175508KLELNZ.htm?opendocument&comments     Augmented reality on the iPhone - a cool new concept with great potential Mon, 31 Aug 2009 13:52:02 +0200 http://www.mindoo.com/web/blog.nsf/dx/31.08.2009135201KLEFX3.htm iPhone Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/31.08.2009135201KLEFX3.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/31.08.2009135201KLEFX3.htm
    Our main work at the moment has to do with a completely new MindPlan version for our partner Haus Weilgut. There already is a standalone MindPlan application on the market that stores its data in Lotus Notes and one version that is directly integrated into the Lotus Notes 8.x client as a Composite Application component.
    This new version is somehow different. Still using Notes/Domino technologies, but with a very innovative approach. Watch the MindPlan blog for announcements in the next weeks.

    I will continue the XPages development and blogging after the next vacation (had to concentrate on MindPlan to produce an alpha test version).

    For now, I've just come across a very cool new concept, called "Augmented reality" for the iPhone that I would like to share with you.

    Here is an article about a sample application that integrates tourist information into the camera image of an iPhone:
    The future is now? Augmented reality comes to the iPhone

    I think the technology has a great potential, not only for tourist information. I think of very funny geo caching and virtual reality shooter games when I the demo video.
    For example something like this on the iPhone: http://www.youtube.com/watch?v=Cix3Ws2sOsU  :-) ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/31.08.2009135201KLEFX3.htm http://www.mindoo.com/web/blog.nsf/dx/31.08.2009135201KLEFX3.htm?opendocument&comments     XPages series #6: Tracking data changes Wed, 22 Jul 2009 17:52:10 +0200 http://www.mindoo.com/web/blog.nsf/dx/22.07.2009175255KLELM7.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/22.07.2009175255KLELM7.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/22.07.2009175255KLELM7.htm
    Remember part 4 of this series, when we introduced the Actor and ActorList implementation:
    Our ActorList Java bean is the so called backing bean behind the ActorList XPage, which means that it is used to provide the data and application logic needed by that XPage.
    Moving all the code from the XPage to the backing bean helps us to separate the UI from the business logic. It improves code reuse and testing/debugging.

    In part 4 I described how to show your own Java objects in a data table control and in a repeat control. We used this technology to display a list of Actor objects in read-only mode.
    As I said in the article, you can replace the computed fields in the data table by edit boxes to make the Actor object list editable. JSF then calls the setter methods of the Actor objects with the new values.

    That works, but the architecture isn't really smart that way.

    In this article, I would like to add a data store to our little scenario, that we will use to store the data changes to a persistent data storage.
    That way we can
    • check whether the current user is allowed to change the data
    • write the changes and the previous values to a log file (e.g. for auditing purpose)
    • do data transformation, like storing the information of one data object in two places (e.g. two Notes documents or Notes and SQL)
    • trigger additional data changes, like inheriting field values to/from other documents

    In short: We get complete control over the data that is written to disk.

    Our today's result will look like this:

    Image:XPages series #6: Tracking data changes

    (we concentrate on the functionality first, this is not a web design series ;-) )


    It's the data table of part 4, but with edit boxes and a button "Save changes". That button triggers the save operation to store the modified Actor table row entries into our own data store.
    The logging field at the bottom contains a list of data comparison results (I had changed the comment property of the first Actor in the list and pressed the save button).

    Our data store

    Let's start with a simple Java interface definition of our data store:

    package com.acme.actors.model;
    import java.util.List;

    /**
     * Interface for a CRUD-based Data Store
     */
    public interface DataStore {
           /**
             * The method creates a new Actor instance
             *
             * @return new Actor
             */
            public Actor createActor();

           /**
             * The method searches for an Actor by its ID in the data store
             *
             * @param id Actor ID
             * @return Actor or null
             */
            public Actor findActorById(String id);

           /**
             * Writes changes made to the specified Actor instance to the data store
             * to store them permanently.
             *
             * @param changedActor Changed Actor instance
             */
            public void updateActor(Actor changedActor);

           /**
             * The method delete an Actor from the data store
             *
             * @param id Actor ID
             */
            public void deleteActor(String id);

           /**
             * The method returns a list of Actor objects, ordered by the lastname property.
             * This list cannot be modified. Use the DataStore methods instead.
             *
             * @return List
             */
            public List<Actor> getActorsByLastname();
    }

    That's a data store interface for our Actor objects following the CRUD pattern. CRUD stands for Create, Read, Update and Delete.
    It's not a concrete implementation. A Java interface acts like a blueprint for the implementations: they have to implement all the methods of the interface.

    Our implementation, using an in-memory list of objects can be found here: The first interesting thing is how we tell JSF about this concrete data store implementation. We use a new managed bean for that, called DataStoreManager:

    package com.acme.actors.model;

    import javax.faces.FacesException;
    import com.acme.tools.JSFUtil;

    /**
     * The DataStoreManager manages the {@link DataStore} instance that is
     * used for the data storage of the application.
     */
    public class DataStoreManager {
            private String m_storageClass;
            private DataStore m_store;

            public DataStoreManager() {}

           /**
             * This method is used by JSF to set the class name of the
             * {@link DataStore} to be used.
             *
             * @param className class name
             */
            @SuppressWarnings("unchecked")
            public void setStorageClass(String className) {
                    m_storageClass=className;
                    try {
                            //try to initialize the data store using Java reflection
                            Class<? extends DataStore> storageClazz=(Class<? extends DataStore>) getClass().forName(className);
                            m_store=(DataStore) storageClazz.newInstance();
                    } catch (ClassNotFoundException e) {
                            throw new FacesException(e);
                    } catch (IllegalAccessException e) {
                            throw new FacesException(e);
                    } catch (InstantiationException e) {
                            throw new FacesException(e);
                    }
            }

           /**
             * Returns the class name of the {@link DataStore} to be used.
             *
             * @return class name
             */
            public String getStorageClass() {
                    return m_storageClass;
            }

           /**
             * Returns the data store instance for the data access.
             *
             * @return data store
             */
            public DataStore getStore() {
                    return m_store;
            }

           /**
             * Convenience method to access the instance of the DataStoreManager for
             * the current user from the session scope.
             *
             * @return DataStoreManager instance
             */
            public static DataStoreManager getManager() {
                    return (DataStoreManager) JSFUtil.getBindingValue("#{DataStoreManager}");
            }
    }

    Take a look at two methods in particular: setStorageClass(String) and the static method getManager().

    We use setStorageClass(String) to tell the DataStoreManager bean which implementation of the DataStore interface it should use. It then tries to instantiate the concrete data store, for our test implementation the class is "com.acme.actors.model.mydb.MyDataStore".

    The static method getManager() uses one of the helper functions of series part 5 to return the session scope instance of the DataStoreManager.

    So in our Java code, we can quickly do data store operations like this

    DataStore ds=DataStoreManager.getManager().getStore();
    ds.deleteActor("12345");

    Actor newActor=ds.createActor();
    newActor.setFirstname("Humphrey");
    newActor.setLastname("Bogart");
    newActor setComment("Casablanca");
    ds.updateActor(newActor);

    JSF will take care that the DataStoreManager bean is created when we call getManager(). We can even call getManager() before the bean is used anywhere in an XPage.

    Please note that the code above does not contain any Lotus Notes specific code like bindings to Notes documents and views, just our own simple Java classes and interfaces.
    Data handling is done in our code.

    Setting default bean properties

    How do we know when to tell the DataStoreManager the class name of our data store?
    That's easy: We let JSF do it automatically. By adding a small piece of code in the faces-config.xml, we can define default values that should be set when a bean is created by JSF.

    <?xml version="1.0" encoding="UTF-8"?>
    <faces-config>
      <managed-bean>
        <managed-bean-name>DataStoreManager</managed-bean-name>
        <managed-bean-class>com.acme.actors.model.DataStoreManager</managed-bean-class>
        <managed-bean-scope>session</managed-bean-scope>
       <managed-property>
          <property-name>storageClass</property-name>
          <value>com.acme.actors.model.mydb.MyDataStore</value>
        </managed-property>
      </managed-bean>

      <managed-bean>
        <managed-bean-name>ActorList</managed-bean-name>
        <managed-bean-class>com.acme.actors.controller.ActorList</managed-bean-class>
        <managed-bean-scope>session</managed-bean-scope>
      </managed-bean>

      <managed-bean>
        <managed-bean-name>Log</managed-bean-name>
        <managed-bean-class>com.acme.logging.Log</managed-bean-class>
        <managed-bean-scope>session</managed-bean-scope>
      </managed-bean>
    </faces-config>

    You can set more than just string properties. For example, you can fill a Map with key/value pairs or predefine the values of a Java List. Please refer to the JSF documentation I mentioned in part 2 of this series for the exact syntax.

    Detecting object property changes

    There are certainly many ways to track property changes for the data objects. For this example, I chose to store a list of ObjectPropertyChangeEvents in my data objects. Such a change event basically is a container for the name of the property (like "Firstname", "Lastname", "Comment"), its old and its new value. We will generate such events in the setter methods of our new Actor class implementation like this:

    public void setFirstname(String newFirstName) {
            if (!StringUtil.isEqual(m_firstName, newFirstName)) {
                    //first name has changed. Store old and new value in a change event
                    ObjectPropertyChangeEvent evt=new ObjectPropertyChangeEvent(FLD_ACTOR_FIRSTNAME, m_firstName, newFirstName);
                    m_firstName=newFirstName;
                    addChangeEvent(evt);
            }
    }

    Here is the base implementation of a data object. It contains all the property change management methods. Our Actor class will now be a subclass of DataObject  to leverage those methods.

    package com.acme.actors.model;

    import java.util.Hashtable;

    /**
     * Abstract base object for a data store object that provides an internal list
     * of changed object properties. The purpose is to quickly get information
     * in a data source what property changes have to be transferred to
     * persistent storage.
     */
    public abstract class DataObject {
            private boolean m_initialized=false;
            private Hashtable<String, ObjectPropertyChangeEvent> m_changeEvents;

            public DataObject() {}

            protected void init() {
                    if (!m_initialized) {
                           //lazy creation of member variables
                            m_changeEvents=new Hashtable<String, ObjectPropertyChangeEvent>();
                            m_initialized=true;
                    }
            }

           /**
             * Method to check whether properties in this object have been changed.
             *
             * @return <code>true</code> if there are changed properties
             */
            public boolean hasChanges() {
                    init();

                    return !m_changeEvents.isEmpty();
            }

           /**
             * Returns the property change events for this object
             *
             * @return change events or an empty list
             */
            public ObjectPropertyChangeEvent[] getChanges() {
                    init();

                    return m_changeEvents.values().toArray(new ObjectPropertyChangeEvent[m_changeEvents.size()]);
            }

           /**
             * Adds a change event to the internal list. If the property has been changed
             * before, the old and new change event will be merged into one.
             *
             * @param evt change event
             */
            protected void addChangeEvent(ObjectPropertyChangeEvent evt) {
                    init();

                    String fieldId=evt.getFieldId();
                    ObjectPropertyChangeEvent oldEvt=m_changeEvents.get(fieldId);
                    if (oldEvt==null) {
                            m_changeEvents.put(fieldId, evt);
                    }
                    else {
                           //merge old and new event
                            Object oldValue=oldEvt.getOldValue();
                            m_changeEvents.put(fieldId, new ObjectPropertyChangeEvent(fieldId, oldValue, evt.getNewValue()));
                    }
            }

           /**
             * Method to clear the change event list
             */
            public void resetChanges() {
                    m_initialized=false;
                    init();
            }
    }

    Here is the new Actor implementation and the source code of the ObjectPropertyChangeEvent:
    Actor.java - com.acme.actors.model.Actor
    ObjectPropertyChangeEvent.java - com.acme.actors.model.ObjectPropertyChangeEvent

    Our data store is now ready to use and our Actor data objects are prepared to write a change event log when somebody calls the setter methods.

    Adding the "save changes" operation

    At first, we now have to produce code in our ActorList backing bean that handles the save operation: It grabs the changed Actor objects from the data table and sends them to the persistent data store.
    We use another of our helper function for this purpose: JSFUtil.findComponent(String). It traverses the JSF component tree of the current XPage to give us access to the data table (like the getComponent() method does in XPages JavaScript).

    This is our new ActorList backing bean:

    package com.acme.actors.controller;

    import java.util.List;
    import javax.faces.component.UIComponent;
    import javax.faces.component.UIData;
    import com.acme.actors.model.Actor;
    import com.acme.actors.model.DataStoreManager;
    import com.acme.tools.JSFUtil;

    public class ActorList {
            public ActorList() {}

            public List<Actor> getActorsByLastname() {
                   //delegate call to the new data store
                    return DataStoreManager.getManager().getStore().getActorsByLastname();
            }

           public void save() {
                   //grab the data table content and send it to the data store
                    UIComponent table=JSFUtil.findComponent("actorTable");
                    if (table instanceof UIData) {
                           //the table is a subclass of UIData, which gives us access to the row values of the table
                            UIData tableData=(UIData) table;

                            int rows=tableData.getRowCount();
                            int oldRowIndex=tableData.getRowIndex();

                            for (int i=0; i                                tableData.setRowIndex(i);
                                    Object currObj=tableData.getRowData();
                                    if (currObj instanceof Actor) {
                                            Actor currActor=(Actor)currObj;
                                           //send the Actor object to the data store to write changes
                                            //to the persistent storage
                                            DataStoreManager.getManager().getStore().updateActor(currActor);
                                    }
                            }
                            tableData.setRowIndex(oldRowIndex);
                    }
                    else {
                            Log.getInstance().println("Could not find table with id=actorTable");
                    }
            }
    }

    Finally, we need to add the "Save changes" button to the XPage UI with the following JavaScript onClick code:

    var actorList=com.acme.tools.JSFUtil.getBindingValue("#{ActorList}");
    actorList.save();

    Here is a list of remaining files that have been used or changed in this article:
    Ok, guys... the worst part of this series is over ;-). It has become a really long article, even longer than part 4.

    But it's easier than it looks like. Believe me. :o)

    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/22.07.2009175255KLELM7.htm http://www.mindoo.com/web/blog.nsf/dx/22.07.2009175255KLELM7.htm?opendocument&comments     XPages series #5: Helper classes to access the JSF environment and Lotus Notes data Sat, 18 Jul 2009 19:17:37 +0200 http://www.mindoo.com/web/blog.nsf/dx/18.07.2009191738KLENAL.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/18.07.2009191738KLENAL.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/18.07.2009191738KLENAL.htm
    After I had found out how to declare and bind Managed Java Beans in XPages, I tried to produce a small sample application.
    Soon, three questions came up, that I needed to solve, before I could go on:
    • How do I access global JavaScript variables and my declared Java beans?
    • How can I access fields in the current XPage?
    • Calling NotesFactory.createSession() to create a Notes session throws a security exception.
      Is there a way to access Notes API from my bean code?
    Here is the first helper class that has an answer to all three questions:

    package com.acme.tools;

    import javax.faces.application.Application;
    import javax.faces.context.FacesContext;
    import javax.faces.el.ValueBinding;

    public class JSFUtil {
           /**
             * The method creates a {@link javax.faces.el.ValueBinding} from the
             * specified value binding expression and returns its current value.<br>
             * <br>
             * If the expression references a managed bean or its properties and the bean has not
             * been created yet, it gets created by the JSF runtime.
             *
             * @param ref value binding expression, e.g. #{Bean1.property}
             * @return value of ValueBinding
             * throws javax.faces.el.ReferenceSyntaxException if the specified <code>ref</code> has invalid syntax
             */
            public static Object getBindingValue(String ref) {
                    FacesContext context=FacesContext.getCurrentInstance();
                    Application application=context.getApplication();
                    return application.createValueBinding(ref).getValue(context);
            }

           /**
             * The method creates a {@link javax.faces.el.ValueBinding} from the
             * specified value binding expression and sets a new value for it.<br>
             * <br>
             * If the expression references a managed bean and the bean has not
             * been created yet, it gets created by the JSF runtime.
             *
             * @param ref value binding expression, e.g. #{Bean1.property}
             * @param newObject new value for the ValueBinding
             * throws javax.faces.el.ReferenceSyntaxException if the specified <code>ref</code> has invalid syntax
             */
            public static void setBindingValue(String ref, Object newObject) {
                    FacesContext context=FacesContext.getCurrentInstance();
                    Application application=context.getApplication();
                    ValueBinding binding=application.createValueBinding(ref);
                    binding.setValue(context, newObject);
            }

           /**
             * The method returns the value of a global JavaScript variable.
             *
             * @param varName variable name
             * @return value
             * @throws javax.faces.el.EvaluationException if an exception is thrown while resolving the variable name
             */
            public static Object getVariableValue(String varName) {
                    FacesContext context = FacesContext.getCurrentInstance();
                    return context.getApplication().getVariableResolver().resolveVariable(context, varName);
            }

           /**
             * Finds an UIComponent by its component identifier in the current
             * component tree.
             *
             * @param compId the component identifier to search for
             * @return found UIComponent or null
             *
             * @throws NullPointerException if <code>compId</code> is null
             */
            public static UIComponent findComponent(String compId) {
                    return findComponent(FacesContext.getCurrentInstance().getViewRoot(), compId);
            }

           /**
             * Finds an UIComponent by its component identifier in the component tree
             * below the specified <code>topComponent</code> top component.
             *
             * @param topComponent first component to be checked
             * @param compId the component identifier to search for
             * @return found UIComponent or null
             *
             * @throws NullPointerException if <code>compId</code> is null
             */
            public static UIComponent findComponent(UIComponent topComponent, String compId) {
                    if (compId==null)
                            throw new NullPointerException("Component identifier cannot be null");

                    if (compId.equals(topComponent.getId()))
                            return topComponent;

                    if (topComponent.getChildCount()>0) {
                            List childComponents=topComponent.getChildren();

                            for (UIComponent currChildComponent : childComponents) {
                                    UIComponent foundComponent=findComponent(currChildComponent, compId);
                                    if (foundComponent!=null)
                                            return foundComponent;
                            }
                    }
                    return null;
            }
    }

    How to access other beans and bean properties
    You can use the methods JSFUtil.getBindingValue() and JSFUtil.setBindingValue() to do that:

    //Returns our previously declared session scope bean ActorList. The bean is created if it does not exist yet
    ActorList actors=(ActorList) JSFUtil.getBindingValue("#{ActorList}");

    //Get the value of a bean property
    List<Actor> actorList=(List<Actor>) JSFUtil.getBindingValue("#{ActorList.actors}");

    //Set the value of a bean property
    JSFUtil.setBindingValue("#{ActorList.actors}", new ArrayList<Actor>());

    Hint:
    The expression language is more powerful than you might think. An expression like

    #{ActorList.actorsById["12345"].firstname}

    could for example return the firstname of the actor with the unique identifier "12345" from the ActorList bean.

    What the expression resolver does internally is grab your declared ActorList bean from the session scope, look out for a method "getActorsById()" and check its return value. If the return value is of type java.util.Map (like a List in Lotusscript), if would then call its get method with the hash key "12345" (like Map.get("12345")) to get the Map entry for that key. In our case, this could be an Actor object.
    Finally, the resolver then searches for a method getFirstname() in the object and returns its value.

    How to access fields in the current XPage
    An XPage (like any JSF page) consists of a tree of UIComponent objects. The top element of that tree can be retrieved with

    UIViewRoot view=FacesContext.getCurrentInstance().getViewRoot();

    Our helper function JSFUtil.findComponent(String) traverses the whole component tree and searches for an UIComponent with the specified identifier.
    That's basically what the XPage JavaScript function getComponent(String) does.

    So the following code

    UIComponent comp=JSFUtil.findComponent("actorTable");

    would for example give us access to the table of actors that we created in the previous article of this series.
    It depends on the component type, how much we can do with the components. UIComponent is just the base class that all the various UI components extend. We will see an example use case for accessing the component tree in a later article.

    How to access global JavaScript variables / How to get the current Lotus Notes Session
    It you know the answer to the first question, you know the answer to the second. That's because the current Lotus Notes session and database are stored in global JavaScript variables.

    So here is helper class number two, that leverages the new JSFUtil.getVariableValue(String) function to grab a global JavaScript variable:

    package com.acme.model.notes;

    import lotus.domino.Database;
    import lotus.domino.Session;
    import com.acme.tools.JSFUtil;

    public class DominoAccess {
           /**
             * Returns the current Notes session instance of the Javascript engine.
             *
             * @return Session
             */
            public static Session getCurrentSession() {
                    return (Session) JSFUtil.getVariableValue("session");
            }

           /**
             * Returns the current Notes database instance of the Javascript engine.
             *
             * @return Database
             */
            public static Database getCurrentDatabase() {
                    return (Database) JSFUtil.getVariableValue("database");
            }
    }

    Sample usage:
    Session session=DominoAccess.getCurrentSession();
    String userName=session.getUserName();

    This returns the user name of your Lotus Notes ID if you are logged in and the name of the Domino server ID if you are not logged in.

    Hint
    Please note that the session and all child Notes objects like databases or documents are disposed (by calling their recycle() method) quite often. I haven't figured out so far when this exactly happens.
    So do not store Notes objects locally in your code. Instead, grab a fresh session, transfer the Notes data into your own objects and do not forget to call recycle() on Notes objects that you don't need any more (like for normal Notes Java API coding) to avoid high memory allocation.


    That's it for today. A very technical article without a screenshot or real-life example. Sorry about that. But it's necessary to have this knowledge base for the next articles.
    I'm curious if anybody has already started to build his own sample application. Feel free to write a comment!
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/18.07.2009191738KLENAL.htm http://www.mindoo.com/web/blog.nsf/dx/18.07.2009191738KLENAL.htm?opendocument&comments     XPages series #4: Backing Bean Management with XPages Thu, 16 Jul 2009 09:58:16 +0200 http://www.mindoo.com/web/blog.nsf/dx/16.07.2009095816KLEBCY.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/16.07.2009095816KLEBCY.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/16.07.2009095816KLEBCY.htm
    At the end of this blog entry, you should get the trick how the XPages user interface can be connected to backend Java Beans. I will follow up with another article that contains code snippets you might need after you start working with this technology in a real-life project.

    And I promise to show an example at the very end of this series, to not leave you alone, totally confused with Java, Beans, Bindings, Expression Language and other things. :-)

    Warning! This article is looooong ;-).

    Separation of UI and application logic
    A Backing Bean is a Java Bean that is associated with UI components used in a page. The purpose of Backing Beans is to separate the definition of UI components from objects that perform application-specific processing and hold data. That way your XPage will contain more or less just the UI, while the application logic is stored in the bean.

    To continue with our Movie Actor database, we start with a pretty simple Java class that is a container for the data of an actor:

    package com.acme.actors.model;

    public class Actor {
            private String m_id;
            private String m_firstName;
            private String m_lastName;
            private String m_comment;
           
            public Actor() {}
           
            public Actor(String id, String firstName, String lastName, String comment) {
                    m_id=id;
                    m_firstName=firstName;
                    m_lastName=lastName;
                    m_comment=comment;
            }

            public String getId() {
                    return m_id;
            }
           
            public void setId(String newId) {
                    m_id=newId;
            }
           
            public String getFirstname() {
                    return m_firstName;
            }
           
            public void setFirstname(String newFirstName) {
                    m_firstName=newFirstName;
            }
           
            public String getLastname() {
                    return m_lastName;
            }
           
            public void setLastname(String newLastname) {
                    m_lastName=newLastname;
            }
           
            public String getComment() {
                    return m_comment;
            }
           
            public void setComment(String newComment) {
                    m_comment=newComment;
            }
    }

    Well, pretty self-explanatory. The class will be is used to store the firstname, lastname, a comment and a unique identifier of an actor. Notice, that the class is completely independent from Lotus Notes. The identifier field might be later on used for a Notes document's universal id (in case we load Notes data), but it could just as well be something completely different like a primary key of table rows in a SQL database.

    Let's take a look at our first Backing Bean. It will be used to provide the backend logic of our actor list XPage:

    package com.acme.actors.controller;

    import java.util.ArrayList;
    import java.util.List;
    import java.util.UUID;
    import com.acme.actors.model.Actor;

    public class ActorList {
            private List<Actor> m_actors;

            public ActorList() {}

            private void init() {
                    if (m_actors==null) {
                            //list is empty and needs to be filled
                            m_actors=new ArrayList<Actor>();

                            m_actors.add(new Actor(createNewId(), "Sean", "Connery", "James Bond"));
                            m_actors.add(new Actor(createNewId(), "Daniel", "Craig", "James Bond"));
                            m_actors.add(new Actor(createNewId(), "Catherine", "Zeta-Jones", "Ocean's Twelve"));
                            m_actors.add(new Actor(createNewId(), "Tobey", "Maguire", "Spiderman"));
                            m_actors.add(new Actor(createNewId(), "Kirsten", "Dunst", "Spiderman"));
                            m_actors.add(new Actor(createNewId(), "John", "Travolta", "Pulp Fiction"));
                            m_actors.add(new Actor(createNewId(), "Bruce", "Willis", "Die Hard"));
                            m_actors.add(new Actor(createNewId(), "Christopher", "Lee", "Dracula"));
                            m_actors.add(new Actor(createNewId(), "Patrick", "Stewart", "Star Trek"));
                            m_actors.add(new Actor(createNewId(), "Charlton", "Heston", "Planet of the Apes"));
                    }
            }

            private String createNewId() {
                    //create a new unique identifier for a list entry
                    return UUID.randomUUID().toString();
            }

            public List<Actor> getActors() {
                    //init() initializes the actor list the first time it is called
                    init();

                    return m_actors;
            }

            public void setActors(List<Actor> newActors) {
                    m_actors=newActors;
            }
    }

    Our class does not contain any real business logic at the moment. It contains a list of ten actors that are written into the internal variable "m_actors", which is returned by the method "getActors()".
    We will use this method in our XPage, to feed the rows of a table.

    Bean declaration in faces-config.xml
    Next we need to tell the JavaServer Faces runtime about our new bean.
    To do this, modify the faces-config.xml file and add the following <managed-bean> section:

    <?xml version="1.0" encoding="UTF-8"?>
    <faces-config>
      <managed-bean>
        <managed-bean-name>ActorList</managed-bean-name>
        <managed-bean-class>com.acme.actors.controller.ActorList</managed-bean-class>
        <managed-bean-scope>session</managed-bean-scope>
      </managed-bean>
    </faces-config>

    With this information, the JSF runtime is able to resolve an expression language construct like "#{ActorList}" to find our bean. It knows that the bean has the classname "com.acme.actors.controller.ActorList" and can create a new instance of it.
    We also tell the runtime something about the bean's life span, called "scope", in this line:

    <managed-bean-scope>session</managed-bean-scope>

    The scope "application" means that there will be only one instance of the bean in the whole application (=one bean for all users, useful for translation dictionaries). With"session", one bean is created for the whole session of a single user, e.g. to hold personal profile information. With the scope"request" you can create a bean that is only valid for a single HTTP request (to pass data from one page to the other) and the scope "none"  lets the JSF runtime dispose the bean after every HTTP request. In that case, it is stored nowhere automatically.

    And now, the end is near
    To bring all the pieces together, we now create our ActorList XPage and insert a data table control with three columns:

    Image:XPages series #4: Backing Bean Management with XPages

    For the table's binding, we click on "Advanced", select "Expression Language (EL)" from the combo box and enter the following text: ActorList.actors.
    This produces the string "#{ActorList.actors}" in the source code of the XPage. When the JavaServer Faces runtime resolves this expression to retrieve the row data for the table, it fetches/creates our ActorList Java Bean from the sessionScope and searches for a method "getActors" in it. This is our method that returns the List of actors.

    The table will now display each List entry in its own table row. By entering the string "currentActor" in the Collection name field (see #2 in the screenshot above), the row data (the current Actor objects) can be accessed in the row controls (in my case three computed fields for the firstname, lastname and comment):

    Image:XPages series #4: Backing Bean Management with XPages

    Here is the full source code of the ActorList XPage:

    <?xml version="1.0" encoding="UTF-8"?>
    <xp:view xmlns:xp="http://www.ibm.com/xsp/core">
            <xp:dataTable rows="5" id="actorTable" var="currentActor"
                    style="width:50%" value="#{ActorList.actors}">
                    <xp:this.facets>
                            <xp:pager layout="Previous Group Next" xp:key="header" id="pager1">
                            </xp:pager>
                            <xp:pager layout="Previous Group Next" xp:key="footer" id="pager2">
                            </xp:pager>
                    </xp:this.facets>
                    <xp:column id="firstnameColumn">
                            <xp:text escape="true" id="firstnameField" value="#{currentActor.firstname}">
                            </xp:text>
                    </xp:column>
                    <xp:column id="lastnameColumn">
                            <xp:text escape="true" id="lastnameField" value="#{currentActor.lastname}">
                            </xp:text>
                    </xp:column>
                    <xp:column id="commentColumn">
                            <xp:text escape="true" id="commentField" value="#{currentActor.comment}">
                            </xp:text>
                    </xp:column>
            </xp:dataTable>
    </xp:view>

    And finally:
    This is how our example looks like. It's a table with our in-memory Actor Java objects:

    Image:XPages series #4: Backing Bean Management with XPages

    Instead of a data table, you could of course also use a repeat control to have full control over the generated code. To make the table cells editable, just use an edit box instead of the computed fields. The XPages/JavaServer Faces runtime will automatically inform you about the new values by calling the set-methods of the Actor objects.

    Hint #1
    The method "getActors()" is called on every page refresh and also when the user switches from page 1 of the table to page 2. So you should make sure that you do some caching in your bean and avoid CPU intensive data lookups on every call.

    Hint #2:
    Please note that we return a Java List (java.util.List) implementation in our method "getActors()".
    Nobody said that all the data needs to be in-memory when the data table component calls "getActors()". When you develop your own List implementation, you have full control, which data really has to be loaded from your (external) data store. The table/pager only needs the currently visible rows of the active page.

    Hint #3
    You should avoid to return a Java Collection (java.util.Collection) instead of the Java List in the "getActors()" method.
    That does works, but the pager around the data table needs to know how many elements there are, to calculate the amount of pages for the navigation. Since a Java Collection does not return the total number of entries, the pager calls Collection.toArray(), which grabs the whole data list as an array into memory. That might kill the server for large amounts of data.
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/16.07.2009095816KLEBCY.htm http://www.mindoo.com/web/blog.nsf/dx/16.07.2009095816KLEBCY.htm?opendocument&comments     XPages series #3: How to use version control systems in DDE Wed, 15 Jul 2009 18:02:40 +0200 http://www.mindoo.com/web/blog.nsf/dx/15.07.2009180240KLELTQ.htm DDE Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/15.07.2009180240KLELTQ.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/15.07.2009180240KLELTQ.htm previous posting of the XPages series, I said I'm going to talk about faces-config.xml next, but I just wanted to add a side note, because the topic "Version Control in Domino Designer on Eclipse" seems to be quite interesting for the developer community.

    As you might know, DDE 8.5 is not able to do proper version control for your Notes database, because the CVS/SVN plugins of the underlying Eclipse platform do not support a virtual filesystem (like DDE uses it).
    But there is a workaround, at least for the Java code that will contain our application backend logic.

    In my posting, I showed how to add a folder to the classpath of the NSF project. The Java content was stored in the "WebContent/WEB-INF/source" folder of the database project.

    Actually, there were two buttons to add content to the build path in the project properties dialog:

    Image:XPages series #3: How to use version control systems in DDE

    One is "Add Folder" to add a folder of the NSF project. Now we click on the other button "Link Source" instead:

    Image:XPages series #3: How to use version control systems in DDE

    You can use this "Link Source" feature of Eclipse to include external folders to your project. The external folders can then be part of any version control system you like.

    Simply press "Refresh" on that folder in DDE to let it catch any changes you make in external editors. DDE will also notice changes automatically when a Java file is already open in the editor.
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/15.07.2009180240KLELTQ.htm http://www.mindoo.com/web/blog.nsf/dx/15.07.2009180240KLELTQ.htm?opendocument&comments     XPages series #2: Setting up the database Wed, 15 Jul 2009 15:25:05 +0200 http://www.mindoo.com/web/blog.nsf/dx/15.07.2009152504KLEHR8.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/15.07.2009152504KLEHR8.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/15.07.2009152504KLEHR8.htm It's called "The Complete Reference JavaServer Faces" from Chris Schalk and Ed Burns.
    I don't know if I should recommend you buying it, because IBM has changed most of the original JSF code syntax. So you will not be able to simply copy&paste snippets from the book to the XPages editor, but it's useful to understand the bean management concept and the syntax of the Expression Language (EL) that you can also use in XPages to bind UI components like fields with backend data (beans and Notes documents).

    For me it looks like redefining the JSF tag syntax and directly binding UI fields to Notes document items have been done to create a "new XPages product" from JavaServer Faces and to make it easier for the classic Notes developers to work with it. Unfortunately, this make it unnecessarily hard for experienced JSF coders to jump over to XPages. And no existing JSF applications can run in XPages without being rewritten.

    Let's get started.

    Although we do most of our XPages development on the Design Partner program 8.5.1 prebetas, we made sure that everything that will be demonstrated in the following articles has been created and tested using a 8.5 client and server.

    Creating a new database
    Our first goal is to create a database with an XPage that contains a list of our favorite actors. An actor should have a firstname, lastname and a comment property for the beginning, all three are of type string.
    Our data will not come from Notes documents, but from our own (simulated) in-memory data store.

    We start by creating a new database on the Domino server. Let's call it "Movie Actors".

    In DDE, open the database and switch to the Java Perspective, either by using "Window/Open Perspective/Other..." and selecting "Java" in the selection dialog, or by simply clicking on our new DDE toolbar icon.

    The database looks like this:

    Image:XPages series #2: Setting up the database

    Domino Designer on Eclipse (DDE) is based on the Eclipse framework. What you see in the picture is the Eclipse project representation of our database (Eclipse uses a virtual filesystem, so most of these files do not exist on your disk, and only some of them are stored in the NSF file).
    There are two interesting folders for our upcoming development: "Local" and "WebContent/WEB-INF".

    Local
    The Local folder is what it's called - a local repository where Lotus Notes creates necessary Java classes like a dummy Activator.java file which is needed to be able to treat the NSF project as an Eclipse plugin.
    You should not mess around in the "Local" folder and add your own code! It's created only on your machine or on the server. It does not replicate and DDE will probably overwrite your changes.
    Instead, we're gonna add our own source code folder later on.

    WebContent/WEB-INF
    The content of the WEB-INF folder is part of the NSF file. JSF coders will already recognize the content in the screenshot above. The "faces-config.xml" is the central definition file in the JavaServer Faces world.
    One purpose of the faces-config.xml is to define the Java Beans that your application may use, e.g. as a backend class for the user interface (so called backing beans) to get/set form field values and provide code for action button and command links.

    Adding a source folder
    As I have said before, the "Local" folder cannot be used to store your own Java code. So we need to add a folder to the build path of the project.
    To do this, right click on the project name and select "Properties" from the context menu. Then navigate to the "Build path" section of the properties dialog:

    Image:XPages series #2: Setting up the database

    Here you see the "Local" folder as part of the build path. We will add another one. Please click on "Add Folder", then navigate to the "WEB-INF" folder in the tree and press "Create New Folder":

    Image:XPages series #2: Setting up the database

    We call the new folder "source". After closing the dialogs, you can see your new Java coding playground in the tree:

    Image:XPages series #2: Setting up the database

    Everything you do in this folder and its subfolders will be stored in the NSF file of your database and replicated to the server.

    Hint #1
    If DDE 8.5 shows error dialogs like "Resource is out of sync" when you edit files inside the project tree, please right click on the parent folder and use the "Refresh" function in the context menu, then double click again on the file.
    This seems to be an intermittent issue in DDE with the virtual filesystem.

    Hint #2
    Even if you do pure XPages/Domino data store development, adding a source folder might be interesting for you. In SSJS (Server-side JavaScript), you can now access your new Java code like this, for example in a computed field or label on an XPage:

    //create an instance of our class
    var myObj=new com.acme.test.MyClass();
    //let it produce a string and return it as the value of the computed field
    return myObj.produceSomething();

    We're done with part 2
    Your Java environment is now set up. In the next posting, we're gonna take a look at the faces-config.xml file.

    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/15.07.2009152504KLEHR8.htm http://www.mindoo.com/web/blog.nsf/dx/15.07.2009152504KLEHR8.htm?opendocument&comments     XPages series #1: The vision of a better XPages architecture Wed, 15 Jul 2009 11:45:36 +0200 http://www.mindoo.com/web/blog.nsf/dx/15.07.2009114536KLEDG4.htm XPages Karsten Lehmann http://www.mindoo.com/web/blog.nsf/dx/15.07.2009114536KLEDG4.htm?opendocument&comments http://www.mindoo.com/web/blog.nsf/dx/15.07.2009114536KLEDG4.htm
    Maybe that's because it's a Notes technology and therefore Rapid Application Development driven, maybe because XPages is just too new, so most of the developers are happy to simply achieve somehow what they want to do. And of course, the already existing benefits they get from their code compared to classic Domino web development makes them feel that this is already a giant step forward.

    Yes, it is already a great progress. But there is more under the XPages surface than you think.

    My motivation for digging deeper into the XPages architecture and the underlying JavaServer Faces technology was driven by the following facts:
    • our development goal was to use the same business logic API for both the XPages UI and backend processes to modify the application data
    • we wanted to have more control of the data storage, like monitoring/logging data changes
    • we needed support for large amounts of none-Notes data
    • we wanted CVS support for the code we produce in Domino Designer on Eclipse
    • maybe later on, most of the code should also run in a different environment, like a none-Notes data store
    • and finally: I personally absolutely do not like JavaScript as a development language for server-side scripting at all.
      I'm a Java guy. I like type-safety of the code and I love being able to debug what I do.  ;-)
    So the following XPages series postings will show you a completely alternative way to develop XPages applications. We still use the XPages design element, but we do not bind it to Notes documents.
    Most of our code will be developed in backend Java classes, using a technology called "Managed Beans".


    Click here to see a list of all the articles published so far: XPages articles
    ]]>     http://www.mindoo.com/web/blog.nsf/dxcomments/15.07.2009114536KLEDG4.htm http://www.mindoo.com/web/blog.nsf/dx/15.07.2009114536KLEDG4.htm?opendocument&comments