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. ^[6]

Tapestry doesn't mandate anything about the Visit object's class. The type of the visit property is Object. In Java code, accessing the Visit object involves a cast from Object to an application-specific class. The following example demonstrates how a listener method may access the visit object.

public void formSubmit(IRequestCycle cycle)
{
    MyVisit visit = (MyVisit)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:

    MyVisit visit = (MyVisit)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).

<application name="My Application">
  <property name="org.apache.tapestry.visit-class" value="mypackage.MyVisit"/>

  ...

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 property of 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.