Visit Object

The Visit object is an application-defined object that may be obtained from the engine (via the visit property of the IEngine or IPage). By convention, the class is usually named Visit, but it can be any class whatsoever, even Map.

The name, "Visit", was selected to emphasize that whatever data is stored in the Visit concerns just a single visit to the web application. Tapestry is stricly concerned with providing the presentation layer of the application; it doesn't include any kind of database access, or any other kind of long-term data storage. However, it is very easy to interface a Tapestry application to any kind of backend system.

The following example demonstrates how a listener method may access the visit object.

Example 3.1. Accessing the Visit object

public void formSubmit(IRequestCycle cycle)
{
    Visit visit = (Visit)getPage().getVisit();
    
    visit.doSomething();   
}

In most cases, listener methods, such as formSubmit(), are implemented directly within the page. In that case, the first line can be abbreviated to:

    Visit visit = (Visit)getVisit();

The Visit object is instantiated lazily, the first time it is needed. Method createVisit() of AbstractEngine is responsible for this.

In most cases, the Visit object is an ordinary JavaBean, and therefore, has a no-arguments constructor. In this case, the complete class name of the Visit is specified as configuration property org.apache.tapestry.visit-class.

Typically, the Visit class is defined in the application specification, or as a <init-parameter> in the web deployment descriptor (web.xml).

Example 3.2. Defining the Visit class


<application name="Tapestry Component Workbench">
  <property name="org.apache.tapestry.visit-class" value="org.apache.tapestry.workbench.Visit"/>

  ...

In cases where the Visit object does not have a no-arguments contructor, or has other special initialization requirements, the method createVisit() of AbstractEngine can be overridden.

There is a crucial difference between accessing the visit via the visit property of IPage and the visit property of IEngine. In the former case, accessing the visit via the page, the visit will be created if it does not already exist.

Accessing the visit via the IEngine is different, the visit will not be created if it does not already exist.

Carefully crafted applications will take heed of this difference and try to avoid creating the visit unnecessarilly. It is not just the creation of this one object that is to be avoided ... creating the visit will likely force the entire application to go stateful (create an HttpSession), and applications are more efficient while stateless.