package e4s.tutorial;

import e4s.html.*;
import e4s.servlet.*;
import e4s.application.sysmodule.*;

/**
 * This example illustrates the usage of a module, that is called several times
 * by the e4s framework. Normally, each call causes the framework to create
 * a new instance of this module, and by that you loose the possibility to store
 * local values in the module and re-use them the next time a function out of this
 * module would be called.
 *
 * There are workarounds throught that:
 *
 *  1) Make a variable static, but you loose the ability to hold different values
 *     for each user. Anyway, it can make sense, e.g. when using image or font 
 *     objects that are independent of the user.
 * 
 *  2) You can concentrate data in one or more classes (objects) and use the {@link e4s.servlet.E4ServletImplementation_Intf#setSessionObject}
 *     or {@link e4s.servlet.E4ServletImplementation_Intf#setSessionObject} which is basically also the mechanism how
 *     more complex objects (trees, sorted lists) in the e4s environment are working.
 *
 * Or there is an alternative (which is covered here):
 *
 *  3) You can make your whole module "persistant" as an session object, by instancing
 *     the {@link e4s.servlet.E4ModuleImplementation} class using the secons boolean parameter
 *     in the constructor. This mechanism works simple, but be careful when having a large number
 *     of users, as one object is hold in memory for each user. The size of the object depends on
 *     your private/public/protected fields.
 *
 * {@tutorial Example_PersistantModule}
 *
 * @see e4s.servlet.E4ModuleImplementation#E4ModuleImplementation(E4ServletImplementation_Intf,boolean)
 * @see Example_SessionObjects
 */
public class Example_PersistantModule extends E4ModuleImplementation
{
	public static E4Method functionStart = null;
	
	private java.util.Date  m_first_date = null;
	public  java.util.Date  m_last_date = null;
	public  int             m_called = 0;
	
	public Example_PersistantModule()
	{
		// now, this second parameter makes the difference
		super(true);   
	}

	
	/**
	 * This is the entry point into this module.
	 * 
	 * Store the current time in two local member variables (one for the first call,
	 * and another for the last call). Display current values.
	 *
	 * @param html the output to be created by this function
	 */
	public void functionStart(HTML html)
	{
		if (m_first_date == null)
		{
			html.Message("This function was now called for the first time, the whole module is stored as session object.");
			
			// remember the time when it was first started
			m_first_date = new java.util.Date();
		}
		else
		{
			html.Message("This function was called " + m_called + " times before, the first call has been at " + m_first_date.toString()
							+ " and the last call at " + m_last_date.toString());
			html.P();
		}

		// remember the last date called
		m_last_date = new java.util.Date();

		// increment call counter
		m_called++;
		
		// add some links
		html.P();
		
		// open system function to display session objects in a new window    
		A hrefList = html.A(E4ModuleSystem.listSessionObjects);
		hrefList.openInNewWindow(A.WINDOW_PARAM_RESIZE|A.WINDOW_PARAM_SCROLL);
		hrefList.println("[view objects for the current session]");

		// link again to call this function
		A hrefAgain = html.A(functionStart);
		hrefAgain.println("[do it again]");
	}
	
}