Time for another step in my road ahead. This time I have studied Jeremy Hodge’s presentation at MWLUG 2012. As promised Jeremy will demonstrate how to inject Java in XPages application.

Getting started with Java in Designer & XPages

Java Design element in DDE 8.5.3:

Roll out your own project structure via Package Explorer Eclipse view:

You can customize your Java perspective:

Should reside in the WebContent folder.

What is a package?

A way to organize source code modules by using a namespace to prevent class collisions.
Provides some access control on what is accessible between classes.

Package

In the Package Explorer right click your source folder, select New > Package.

Naming conventions for a Package:

Everything lower-case.
Reverse domain name; Project . Sub-Project
- e.g. com.zetaone.mwlug.ad102

Java class

In the Package Explorer right click the Package, select New > Class.

Naming conventions for a Java class:

UpperCamelCase class name.

The new empty class is created & opened in the workspace.

Access levels to methods:

Public:
- Any other class, in any package can access the method or member field.
Private:
- Can only be accessed within the same class.
Protected:
- Can be access by the current class, sub-classes, or any other class in the same package.
Blank:
- Can be access by the current class, and any other class in the package, but not any sub-classes (unless they are in the same package).

Access Java packages via import e.g. import java.util.Date

Managed beans

Bean

Nothing more than a simple Java class.

Managed bean

A Java Class that conforms to a specific set of requirements so that the XPages runtime can create / discard / etcetera our beans for us when we want to use them. In other words it manages our beans for us.

Three things required for a managed bean:

Argument-less constructor.
Serializable.
Uses Getters / Setters to retrieve / store information.

Constructor

A method:

With no return type.
Has the same name as the class itself.
Does not take any arguments.

public class HelloWorld {

public HelloWorld(/*SEE NO ARGUMENTS HERE*/) {
// Do initialization here if you need to…
}
}

Serialization

The process by which an instance of a class is stored in a form that can be written to disk, the network, etcetera and then converted back into a full in-memory instance (save/restore state).

In most cases basic classes can be serialized by implementing Serializable and adding serialVersionUID.

implements Serializable

This is called an interface. An interface is a predefined set of procedures for transmitting data between different objects.

Serializable defines 2 Methods:

writeObject
readObject

serialVersionUID tracks what version of this class is so that objects serialized with one version are not de-serialized into a different, incompatible version.

private static final long serialVersionUID = 1L;

static:
- The declaration belongs to the class, not the instance, and all instances of the class share the same serialVersionUID instance (not value) and it is stored with the class.
final:
- Once it is assigned, it can’t be assigned again – Must be assigned when its declared, or in the constructor.
1L:
- The “L” makes the 1 and long integer (64bit), rather than the default 32bit integer.

Getters / Setters

Use getters / setters to retrieve or set values inside your class instance.

Declaring a managed bean

Modify faces-config.xml located in WebContent/WEB-INF.
Set the Name, Class, and Scope of the Managed bean.

Usage within Xpages

Use the managed-bean-name to reference the class. Expression Language (EL) converts “helloWorld” to getHelloWorld() and “helloWorldDateTime” to getHelloWorldDateTime() when reading the value from the bean.

But we also defined a setHelloWorld() method. How do we use that to store a value back into our instance?

If the component that you bind to your class member is read/write (ie a text box), it will call the setter to update the new value automatically. You don’t have to do anything else!

EXCEPT: Since we are now storing data in the instance that we want to stick around between requests, we need to update our faces-config.xml to set a different managed-bean-scope, such as view.

After refresh:

Reading & Writing Notes Data in Java

Similarity between reading / writing Notes data in LotusScript, Server-Side JavaScript and Java.

Tips, Tricks, & Gotchas

Compare objects

If you want to compare two objects, the objects need to have a .equals() or .compareTo() method.

If (string1 == string2) {
// This is (almost) never true
}

For objects, the == checks to see if the left and right objects are the same object (same address in memory), not if the string has the same content.

If (string1.equals(string2)) {
// Now we’re cooking…
}

There is also an .equalsIgnoreCase()

Getting SSJS Common Instances in Java

SSJS is a scripting language, so several objects are pre-defined and immediately available to you (ie database, session, sessionAsSigner).

In Java, you need to get the variable resolver, and resolve those variables to get at those objects.

There is a set of helper functions in a JSFUtil class that Jeremy as posted on OpenNTF In a project called mypic (http://xpag.es/?mypic)

Security

At some point you are likely to want to use a 3rd party class. You’ll put the JAR file in your NSF, add it to the build path, and you’ll think life is grand, until.

NoClassDefFoundError

Two main reasons you will get this error

Unresolved Dependencies.
- You didn’t add all the JARs you needed to.
The Security Manager is telling you to take a hike, it doesn’t trust that “type” of code in an NSF.

Edit your $INSTALL\jvm\lib\security\java.policy file and grant all permissions to all code.

Serialization, Recycle, and Notes objects

You can not serialize lotus.domino.* classes, ever, AND they WILL get recycled on you – so having them as class members is dangerous!

Biggest reason is recycle(). Recycling is unique to the Notes/Domino objects because the java objects are a wrapper around the C API objects.

Two ways to get around it.

Only deal with the Notes objects when you have to “go to disk” – i.e. load document, save document, read from a view, etc.
1. Do it all locally within your method, store the contents you read in class members, then discard all Notes objects immediately.
Mark your Notes objects as “transient”, then implement a method to return the cached object.
1. In that method, check to see if the object is valid, and if so, return it, otherwise, get it again.

Recycle

General rules:

You should recycle anything you open when you no longer use it (but one-off documents or databases won’t hurt you too bad) … improves scalability.
Anything you open in a loop, recycle before the next loop – or you’re prone to crash w/ “Out of Memory” errors – DON’T Recycle a session, or anything you get from a resolveVariable() call

Summary

This presentation is another great step learning Java especially in the XPages environment. In the last section of the presentation, “The Fun Stuff”, Jeremy goes into detail describing an example of what you are capable of using Java in XPages. This section is a bit out of my head, right now.

I thank Jeremy for sharing the presentation! I noticed also a second presentation Jeremy held at the MWLUG “Introduction to managed beans“. I add this also to my ‘to-study’-list.