So in the previous part we wrote our first bit of java code, a method ( getMyInternetAddress) in a class ( AboutMe ) in a package ( scary.java.demo ). So the question remains, how do I actually use that in my XPage applications?

So remember that link that had a big ssjs code block in it? To use the new java code instead you can just replace the ssjs with a single line that reads

scary.java.demo.AboutMe().getMyInternetAddress()

and the xpage can be saved and previewed and it will do the exact same as what the long ssjs version did. The generated java for the page now looks like this

XspOutputLink result = new XspOutputLink();
result.setValue("/myOtherPage.xsp");
result.setEscape(true);
setId(result, "link1");
String sourceId = "link1/@text";
String textExpr = "#{javascript:scary.java.demo.AboutMe().getMyInternetAddress()}";
ValueBinding text = evaluator.createValueBinding(result, textExpr, sourceId,String.class);
result.setValueBinding("text", text);
return result;

You will notice that I’m still using ssjs and the resulting java still uses this ValueBinding concept to run the ssjs at runtime. While there are ways to avoid ssjs totally ( which I’ll explain in upcoming parts ) this is actually a tiny little bit better then before because your scary.java.demo.AboutMe class already compiled and optimized by the compiler, meaning it runs much faster then the long ssjs version.

Wouldn’t it be much better if I could get rid of the ssjs entirely? I’ll look at this in the next few parts but next we need to talk about another scary word, Beans…

So here is the SSJS used in the previous part that gets the current users internet address from the addressbook. This is not an example of best practice for writing ssjs, I have purposely made it long-form so I can explain each line

try {
var nabDB:NotesDatabase = session.getDatabase(database.getServer(),"names.nsf",false);
var nabView:NotesView = nabDB.getView("($Users)");
var nabDoc:NotesDocument = nabView.getDocumentByKey(session.getEffectiveUserName());
return nabDoc.getItemValueString("InternetAddress");
} catch(e) {
print(e);
return "No Nab Doc";
}

There is a try/catch designed to always return a default if there is problem,otherwise it just gets the current session, gets the address book,gets the $Users view, looks up the document in the $Users view and returns the value. Pretty simple stuff and possibly something you have done in lotusscript for client apps, the pattern is the same.

Here is the java in the same over-simplified, expanded format. It looks scary because it looks like it is much longer and has some bits you may not be familiar with yet, but don’t worry I’ll try and explain them.

package scary.java.demo;

import lotus.domino.Database;
import lotus.domino.Document;
import lotus.domino.NotesException;
import lotus.domino.Session;
import lotus.domino.View;
import com.ibm.xsp.extlib.util.ExtLibUtil;

public class AboutMe {
public String getMyInternetAddress() {
String result = null;
try {
Session session = ExtLibUtil.getCurrentSession();
Database thisDB = session.getCurrentDatabase();
Database nabDB = session.getDatabase(thisDB.getServer(),"names.nsf", false);
View nabView = nabDB.getView("($Users)");
Document nabDoc = nabView.getDocumentByKey(session.getEffectiveUserName());
result = nabDoc.getItemValueString("InternetAddress");
} catch (NotesException e) {
System.out.print(e);
result = "No NAB Doc";
}
return result;
}
}

Really! It is very simple.

I promise!

Ok, lets take it bit by bit.

The first bit is this thing called a package. I’ve named this package as scary.java.demo but in reality you should give your package names good values. The normal way is to reverse your domain name and add some sort of overall grouping name, so this blog runs on qtzar.com so I would name my packages as com.qtzar.groupingname

The next bit is a bunch of import statements. These tell the java compiler what a session or database or view or document consists of. You don’t really have to worry about these. If you use a database in your code the editor will let you know that you need to add the import and will even help out and do it for you ( more on that in another part ). They directly reference things in other packages. So lotus.domino.Database is a reference to something called Document in a package called lotus.domino

The next part is how the thing in the package is given a name. Public means that other things can see it, class just tells it that this is the thing and AboutMe is the name of the thing. If you have access to the source code for the lotus.domino package you would find one of these in there that read ‘Public class Document’ which is what gives a Notes Document a name.

Inside this class is where we can create what are called methods, think of these as the functions in your ssjs library. This particular class only has one method called getMyInternetAddress and it doesn’t accept any parameters.

Inside here is where we have the code that opens the nab, looks for the document and returns the internet email address. it is very similar to the original ssjs. First it gets the current session, then it gets the database, gets the view and gets the document and returns a value. if there is a problem in any stage the try/catch block just returns a default value instead.

The biggest difference between the two is that the java version doesn’t have a ‘var’ statement before each variable and doesn’t use the : objectType notation. Instead the Java line starts with the object type and then the variable name. There are a few other differences but I won’t go into them just yet

You may notice that to get the current session I’m calling a method called getCurrentSession() in an object called ExtLibUtil and if you look at the import statements you can see that this comes from a package called com.ibm.xsp.extlib.util. There are other ways to get the current session but i wanted to give an example of code reuse, somebody else wrote this code so I don’t have to write my own version I can just use theirs.

So that explains how the java code works at a very basic level, in the next part I’ll show you how to actually use the java from your xpage.

You may be asking yourself why you even need to care about Java when it comes to your XPage applications, your xsp file is converted to java and then compiled and ran on the server when called by the browser. You’ll probably even get different answers from different people when you ask that question but for me I see two reasons, speed and reusability.

Reusability is probably something you already do in your applications, lets say you have a requirement to fing the internet email address of the currently logged in user from the addressbook. There are a couple of ways you can do this but you have elected to write some ssjs directly in the computed field control on your page. Later in the same app you need to add a similar field onto a different page, you could copy/page the original field which would duplicate the ssjs code or, in a flash of brilliance , you create a function in a ssjs library and then change both control to call the function, now you only have a single place to change the code for the purpose of showing the currently logged in user’s internet email address. Pat yourself on the back and go grab another coffee.

But what about speed?

The performance of your Xpage application is important for end users, if the page doesn’t appear fast enough they think it is broken and they log a support call and then you look and because you wrote the code and you know it can take .5 of a second to show on screen ( the user wants it in .1 of a second ) you don’t see anything wrong, the user then hates the app and then won’t use it any more.

That ssjs function that you wrote to get the name from the nab is actually a bottleneck in terms of speed. When your xsp file is converted into java the ssjs is not converted, it just becomes a big string of characters that is then passed into another java class that runs it at run time. It is ‘interpreted’ at run time. If there is an error in the code you won’t find out about it till run time and even if you made it a function in a ssjs library it is still only dealt with at runtime.

Here is an example of the java code that is generated by a link control on a page. The text of the link is computed using ssjs.

XspOutputLink result = new XspOutputLink();
result.setValue("/myOtherPage.xsp");
result.setEscape(true);
setId(result, "link1");
String sourceId = "link1/xp:this.text[1]/text()";
String textExpr = "#{javascript:try {ntvar nabDB:NotesDatabase = session.getDatabase(database.getServer(),"names.nsf",false);ntvar nabView:NotesView = nabDB.getView("($Users)");ntvar nabDoc:NotesDocument = nabView.getDocumentByKey(session.getEffectiveUserName());ntreturn nabDoc.getItemValueString("InternetAddress");n} catch(e) {ntprint(e);ntreturn null;n}}";
ValueBinding text = evaluator.createValueBinding(result, textExpr, sourceId,String.class);
result.setValueBinding("text", text);
return result;

Eeek! Java! Run Away, Run Away!

Actually this is very easy to interpret  first it creates a, for the moment lets call it a variable, called result. This variable has a number of things that can be set like the value, and id and text. The scary bit for me was the thing called a ValueBinding but we can ignore exactly what that does right now but you will see that it is being setup with the ssjs that was written for the link and then that is being put into the result variable before the result variable is passed back to the calling java.

The ssjs itself is not converted into java like the rest of the xpage. It is kept as a big blog of text that is then passed into the valueBinding when the class is called to create the page.

If you have a LOT of ssjs on a page then that is a lot of stuff happening at run time and if you have a lot of your business logic in ssjs libraries then it can really slow things down as the ssjs is interpreted at runtime.

So from a speed point of view compiled java is much much faster then ssjs and that alone is a good reason to switch, but it gets even better…

If you have been developing XPage applications you have been developing in Java even if you didn’t know it.

When your web browser hits a .xsp url it is not receiving the xsp file that you have written in DDE, it is receiving HTML that has been generated by a java class which is, in turn, calling other Java classes. The XSP file that you have written in DDE is no longer involved, it was transformed into java without you even knowing.

You can see this for yourself, open the ‘Package Explorer’ view in DDE and open your NSF. In there you will see a folder called ‘local/xsp’ and there will be a java class for each XPage and customer control in your NSF. This is the sourcejava for your xsp page which is later compiled into java byte code. The xml on the xsp design element doesn’t even come into it any more.

If you don’t know Java at all or even very well then if you open one of these compiled pages it is going to scare the heck out of ya. What is a package, why is it doing all these imports, public, private, protected, static, final, void, class, abstract, extends… If you don’t know the language then it does indeed seem very scary.

Now, Tim Tripcony is doing a series on taking the scary out of Java for XPages ( he stole my original title but that’s ok ) but Tim already knows Java where as I’m just starting down the road to Java. I have basic ( not the language ) knowledge of how some bits fit together and how to reference it from XPage applications but right now I’m like the majority of Xpage developers and I use SSJS a lot so in this series I’m going to take you  with me as I discover Java and Xpages and how it all fits together.