XPage Java dev Tutorial 1

Greetings!!

The time has finally arrived for the first tutorial in XPage Java development.  In this tutorial we will learn how to get a handle on the current session in both the opentNTF Domino API (ODA) and the lotus domino API.  We will briefly go over what we did last time, and we will really hammer out some java code.  Stay tuned for next time when we will actually use Java and Custom controls to log data out to the user/XPage_Admin!!  That tutorial is planned to be given to David Leedy to be shown on NotesIn9!  Please make sure that you take a look at the comments that I added to the code which is displayed below!

Happy Programming!


 


 

package com.reederprogramming.utils;

import java.io.Serializable;

import javax.faces.context.FacesContext;

import org.openntf.domino.utils.Factory;

import com.ibm.xsp.extlib.util.ExtLibUtil;
import com.reederprogramming.exceptions.NullDatabaseException;
import com.reederprogramming.exceptions.NullSessionException;

import lotus.domino.Database;
import lotus.domino.Session;

/**
 * This class is going to contain key methods for dealing with the current session.
 * It implements Serializable in case I want to put this class in the sessionScope later and
 * use from JavaScript as well.  This may not be necessary, but it is easy to implement the interface
 * and take it out later if I need to, or leave it in since it does not hurt anything.
 * Note that all java beans MUST implement Serializable if they are going to be retained in server
 * memory.
 * 
 * @see java.io.Serializable
 * 
 * 
 * @author Greg@reederprogramming.com
 *
 */
public class SessionHelper implements Serializable {

	
	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v
	
	/**
	 * This is an example of how to get the current database using the utility class provided 
	 * by the Extension Libraries.  Alternatively, you could alter the getCurrentSession() to
	 * return the database.  Alternatively, you could also create an enum that includes all of
	 * valid strings and use that to get the object you desire from the VariableResolver.
	 * 
	 * @return returns an instance of the lotus.domino.Database.
	 * @throws NullDatabaseException thrown when the current database is null.  Should never happen, but
	 * can during multi-threading operations.
	 * @see lotus.domino.Database
	 * com.reederprogramming.exceptions.NullDatabaseException
	 * 
	 */
	public static Database getCurrentDatabase() throws NullDatabaseException{
		Database d  = null;
		d = ExtLibUtil.getCurrentDatabase();
		if(d == null){
			throw new NullDatabaseException("The current database could not be found!");
			/* This is an example of a checked Exception.  It must be handled or else the 
			*  compiler will yell.
			*/
		}
		return d;
	}
	
	/**
	 * This method shows two different examples.  The first one is how to get the 
	 * current session and the current database using the Factory enum provided by ODA
	 * 
	 * @see org.openntf.domino.utils.Factory
	 * @see org.openntf.domino.Database
	 * @see com.reederprogramming.exceptions.NullDatabaseException
	 * @return returns an instance of org.openntf.domino.Database from the ODA.
	 * @throws NullDatabaseException thrown when the current database is null.  Should never happen, but
	 * can during multi-threading operations.
	 * 
	 */
	public static org.openntf.domino.Database getCurrentODADatabase() throws NullDatabaseException{
		org.openntf.domino.Database d = null;
		d = Factory.getSession().getCurrentDatabase();
		if(d == null){
			throw new NullDatabaseException("The current database could not be found!");
		}
		return d;
	}
	
	/**
	 * This method displays a few things.  First off, we see how to check to see if an object is 
	 * the same as another class, and then we perform a cast to a higher level object.  Additionally,
	 * we see how to use the variableResolver to get the session instance.  This will be the same
	 * session object as returned by the session JavaScript keyword variable.
	 * 
	 * We also see an example of the FIX-ME and TO_DO keywords to aide with development processes.
	 * 
	 * @see lotus.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * 
	 * @return returns an instance of the lotus.domino.Session class
	 * @throws NullSessionException
	 */
	public static Session getCurrentSession() throws NullSessionException{
		Object o = null;
		Session s = null;
		
		FacesContext context = FacesContext.getCurrentInstance();
		o = context.getApplication().getVariableResolver().resolveVariable(context, "session");
		if(o instanceof Session){
			s = (Session)o;
		}
		if(s == null){
			//FIXME add logging!!
			//TODO this must be expanded.
			throw new NullSessionException();
		}
		return s;
	}

	/**
	 * This is a similar example to the getCurrentDatabase() where we use the Extension Library utility
	 * class to get a handle on the current session.  This assumes that the Extension library is used
	 * and will always be used.  Becauase this is a class that should always be available, such an
	 * approach may not be wise.
	 * 
	 * @see com.ibm.xsp.extlib.util.ExtLibUtil
	 * @see lotus.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * 
	 * @return returns an instance of the lotus.domino.Session class.
	 * @throws NullSessionException
	 */
	public static Session getCurrentExtLibSession() throws NullSessionException{
		Session s = null;
		s = ExtLibUtil.getCurrentSession();
		if(s == null){
			//FIXME add logging!!
			throw new NullSessionException();
		}
		return s;
	}
	
	/**
	 * This method illustrates how to get a handle on the current session using ODA.  This is only
	 * one possible way.  Furthermore, it shows how to wrap a normal lotus.domino object (they will always extend
	 * lotus.domino.Base) and return an ODA object.  According to one of the authors (Paul Withers), 
	 * it is however preferable to use the Factory.getSession() method.
	 * 
	 * @see org.openntf.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * @see org.openntf.domino.utils.Factory
	 * 
	 * @return returns an instance of org.openntf.domino.Session
	 * @throws NullSessionException
	 */
	public static org.openntf.domino.Session getCurrentODASession() throws NullSessionException{
		/* 
		 * if you look at the above method declaration, you will notice that I am 
		 * specifying which Session object should be returned.  This is done because other
		 * methods in this class work with the lotus.domino.Session class. I must insert the full
		 * name (including package) in order to prevent ambiguity.  I can, however, debate if
		 * either of them should be imported, or which one makes more sense to import.
		 */
		
		//TODO change this method to simply use the getSession()  This is only for the sake of example
		org.openntf.domino.Session s = null;
		s = Factory.fromLotus(getCurrentSession(), org.openntf.domino.Session.class, null); 
	   
		/* 
		 * normally we would have to catch the NullSessionException given by the getCurrentSession().
		 * in this case, it just makes more sense for it to bubble up to the next method and let it deal with it.
		 */
		if(s == null){
			//FIXME add logging!!
			throw new NullSessionException("Missing session of type: " + org.openntf.domino.Session.class);
		}
		
		return s;
	}
}

 

package com.reederprogramming.exceptions;

/**
 * This is an Exception class to mark that a session object could not be returned.
 * It can be used for ODA or for lotus.
 * 
 * @author greg@reederprogramming.com
 */
public class NullSessionException extends Exception {
	
	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v

	public NullSessionException() {
	}

	public NullSessionException(String arg0) {
		super(arg0);
	}

	public NullSessionException(Throwable arg0) {
		super(arg0);
	}

	public NullSessionException(String arg0, Throwable arg1) {
		super(arg0, arg1);
	}

}

 

package com.reederprogramming.exceptions;

/**
 * This is an Exception class to mark that a Database object could not be returned.
 * It can be used for ODA or for lotus.
 * 
 * @author greg@reederprogramming.com
 */
public class NullDatabaseException extends Exception {
	
	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v

	public NullDatabaseException() {
		super();
	}

	public NullDatabaseException(String arg0) {
		super(arg0);
	}

	public NullDatabaseException(String arg0, Throwable arg1) {
		super(arg0, arg1);
	}

	public NullDatabaseException(Throwable arg0) {
		super(arg0);
	}

}




About reederProgramming

I already have an about me page, so I will just put a quick bit of info here. I am a Notes/Domino developer at holistic-net GmbH located in Hannover, Germany. I use Java primarily at home and as often as I can at work. I have dabbled in C# and a few other languages and platforms. This website started out as a place for me to quickly store and access some of my most important how-tos and has started to become a place where I can really help others too!
Tagged , , , , , , , , , . Bookmark the permalink.

5 Responses to XPage Java dev Tutorial 1

  1. Pingback: XPage dev Why Java - ReederProgramming

  2. Steven Podrouzek says:

    Hey Greg. I watched the tutorial and followed it quite easily. My biggest block to Java is why should I use it? I am having difficulty understanding what the great benefits are, other than getting skilled in a new field.
    I also am perplexed as to why, for example, would I need a session helper when I have session info with my standard XPage. Another thing, having an object of a Domino document and using the object to read and write fields back to my source data seems rather tedious seeing that I can read and write straight to my source data?!?
    I’m missing something for sure because everyone seems to be wanting to go the Java route.
    If I had 1000 users open an XPage application and view a document then why create 1000 objects, one for each document and session helpers. Does that not take needless memory?

    But I am looking forward to the next tutorial!!

    • reederProgramming says:

      Thank you for your awesome questions! I think it best that I take the time to write a blog post about that so that I can take a bit more time and explain my reasoning for preferring Java to JavaScript in my XPage Apps. I will do so within the next few days.

      As for the videos, I am really glad that you are getting into them! The next three are finished and are done as a three-part special which will be released to NotesIn9. I will still embed the videos here, or post links to David Leedy’s website. I will have to see when the time comes what option makes the most sense. I will still post the source code here. The videos are in queue and should be coming out before too long. I need a little bit of time to work on the source databases for the tutorials anyway. — no sense showing everyone how to do classic notes dev…. (not to mention the waste of time editing etc)

    • reederProgramming says:

      One thing I did not touch upon in the blog is regarding the domino document. Keep in mind that the javascript NotesXspDocument IS a DominoDocument. It is simply the JavaScript name for it. As for having a java bean act as a wrapper for a java document, it simply is a matter for your use case. It is not something to do every time.

    • reederProgramming says:

      Just for a quick reference, here is the link http://reederprogramming.com/xpage-dev-why-java/

Leave a Reply

Your email address will not be published. Required fields are marked *