Mindoo Blog - Cutting edge technologies - About Java, Lotus Notes and iPhone

  • XPages series #2: Setting up the database

    Karsten Lehmann  15 July 2009 15:25:05
    Before we begin coding, let me point you to a book that I'm using here to search what is left from JavaServer Faces in the XPages runtime:
    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.