General Questions
Contents
- How do I get started with Tapestry?
- Why does Tapestry use Prototype (in versions before 5.4)? Why not insert favorite JavaScript library here?
- Why does Tapestry have its own Inversion of Control Container? Why not Spring or Guice?
- How do I upgrade from Tapestry 4 to Tapestry 5?
- How do I upgrade from one version of Tapestry 5 to another?
- Why are there both Request and HttpServletRequest?
How do I get started with Tapestry?
The easiest way to get started is to use Apache Maven to create your initial project; Maven can use an archetype (a kind of project template) to create a bare-bones Tapestry application for you. See the Getting Started page for more details.
Even without Maven, Tapestry is quite easy to set up. You just need to download the binaries and setup your build to place them inside your WAR's WEB-INF/lib folder. The rest is just some one-time configuration of the web.xml deployment descriptor.
Why does Tapestry use Prototype (in versions before 5.4)? Why not insert favorite JavaScript library here?
An important goal for Tapestry is seamless DHTML and Ajax integration. To serve that goal, it was important that the built in components be capable of Ajax operations, such as dynamically re-rendering parts of the page. Because of that, it made sense to bundle a well-known JavaScript library as part of Tapestry.
At the time (this would be 2006-ish), Prototype and Scriptaculous were well known and well documented, whereas jQuery was just getting started.
The intent has always been to make this aspect of Tapestry pluggable. Tapestry 5.4 includes the option of either Prototype or jQuery, and future versions of Tapestry will likely remove Prototype as an option..
Why does Tapestry have its own Inversion of Control Container? Why not Spring or Guice?
An Inversion of Control Container is the key piece of Tapestry's infrastructure. It is absolutely necessary to create software as robust, performant and extensible as Tapestry.
Tapestry IoC includes a number of features that distinguish itself from other containers:
- Configured in code, not XML
- Built-in extension mechanism for services: configurations and contributions
- Built-in aspect oriented programming model (service decorations and advice)
- Easy modularization
- Best-of-breed exception reporting
Because Tapestry is implemented on top of its IoC container, and because the container makes it easy to extend or replace any service inside the container, it is possible to make the small changes to Tapestry needed to customize it to any project's needs.
In addition – and this is critical – Tapestry allows 3rd party libraries to be built that fully participate in the configurability of Tapestry itself. This means that such libraries can be configured the same way Tapestry itself is configured, and such libraries can also configure Tapestry itself. This distributed configuration requires an IOC container that fully supports such configurability.
How do I upgrade from Tapestry 4 to Tapestry 5?
There is no existing tool that supports upgrading from Tapestry 4 to Tapestry 5; Tapestry 5 is a complete rewrite.
Many of the basic concepts in Tapestry 4 are still present in Tapestry 5, but refactored, improved, streamlined, and simplified. The basic concept of pages, templates and components are largely the same. Other aspects, such as server-side event handling, is markedly different.
Tapestry 5 is designed so that it can live side-by-side in the same servlet as a Tapestry 4 app, without package namespace conflicts, sharing session data and common resources such as images and CSS. This means that you can gradually migrate a Tapestry 4 app to Tapestry 5 one page (or one portion of the app) at a time.
How do I upgrade from one version of Tapestry 5 to another?
Main Article: How to Upgrade.
A lot of effort goes into making an upgrade from one Tapestry 5 release to another go smoothly. In the general case, it is just a matter of updating the version number in your Maven build.xml or Gradle build.gradle file and executing the appropriate commands (e.g., gradle idea or mvn eclipse:eclipse) to bring your local workspace up to date with the latest binaries.
After changing dependencies, you should always perform a clean recompile of your application.
We make every effort to ensure backwards-compatibility. Tapestry is mostly coded in terms of interfaces; those interfaces are stable to a point: interfaces your code is expected to implement are usually completely frozen; interfaces your code is expected to invoke, such as the interfaces to IoC services, are stable, but may have new methods added in a release; existing methods are not changed.
In rare cases a choice is necessary between fixing bugs (or adding essential functionality) and maintaining complete backwards compatibility; in those cases, an incompatible change may be introduced. These are always discussed in detail in the Release Notes for the specific release. You should always read the release notes before attempting an upgrade, and always (really, always) be prepared to retest your application afterwards.
Note that you should be careful any time you make use of internal APIs (you can tell an API is internal by the package name, org.apache.tapestry5.internal). Internal APIs may change at any time; there's no guarantee of backwards compatibility. Please always check on the documentation, or consult the user mailing list, to see if there's a stable, public alternative. If you do make use of internal APIs, be sure to get a discussion going so that your needs can be met in the future by a stable, public API.
Why are there both Request and HttpServletRequest?
Tapestry's Request interface is very close to the standard HttpServletRequest interface. It differs in a few ways, omitting some unneeded methods, and adding a couple of new methods (such as isXHR()), as well as changing how some existing methods operate. For example, getParameterNames() returns a sorted List of Strings; HttpServletRequest returns an Enumeration, which is a very dated approach.
However, the stronger reason for Request (and the related interfaces Response and Session) is to enable the support for Portlets at some point in the future. By writing code in terms of Tapestry's Request, and not HttpServletRequest, you can be assured that the same code will operate in both Servlet Tapestry and Portlet Tapestry.
Limitations
Contents
How do I add new components to an existing page dynamically?
The short answer here is: you don't. The long answer here is you don't have to, to get the behavior you desire.
One of Tapestry basic values is high scalability: this is expressed in a number of ways, reflecting scalability concerns within a single server, and within a cluster of servers.
Although you code Tapestry pages and components as if they were ordinary POJOs (Plain Old Java Objects -- Tapestry does not require you to extend any base classes or implement any special interfaces), as deployed by Tapestry they are closer to a traditional servlet: a single instance of each page services requests from multiple threads. Behind the scenes, Tapestry transforms you code, rewriting it on the fly.
What this means is that any incoming request must be handled by a single page instance. Therefore, Tapestry enforces the concept of static structure, dynamic behavior.
Tapestry provides quite a number of ways to vary what content is rendered, well beyond simple conditionals and loops. It is possible to "drag in" components from other pages when rendering a page (other FAQs will expand on this concept). The point is, that although a Tapestry page's structure is very rigid, the order in which the components of the page render does not have to be top to bottom.
Why doesn't my service implementation reload when I change it?
Main article: Service Implementation Reloading
Live service reloading has some limitations:
- The service must define a service interface.
- The service implementation must be on the file system (not inside a JAR).
- The implementation must be instantiated by Tapestry, not inside code (even code inside a module class).
- The service must use the default scope (reloading of perthread scopes is not supported).
Consider the following example module:
public static void bind(ServiceBinder binder)
{
binder.bind(ArchiveService.class, ArchiveServiceImpl.class);
}
public static JobQueue buildJobQueue(MessageService messageService, Map<String,Job> configuration)
{
JobQueueImpl service = new JobQueueImpl(configuration);
messageService.addQueueListener(service);
return service;
}
ArchiveService is reloadable, because Tapestry instantiates ArchiveServiceImpl itself. On the other hand, Tapestry invokes buildJobQueue() and it is your code inside the method that instantiates JobQueueImpl, so the JobQueue service will not be reloadable.
Finally, only classes whose class files are stored directly on the file system, and not packaged inside JARs, are ever reloadable ... generally, only the services of the application being built (and not services from libraries) will be stored on the file system. This reflects the intent of reloading: as an agile development tool, but not something to be used in deployment.
How do I run multiple Tapestry applications in the same web application?
Running multiple Tapestry 5 applications is not supported; there's only one place to identify the application root package, so even configuring multiple filters into multiple folders will not work.
Support for multiple Tapestry applications in the same web application was a specific non-goal in Tapestry 5 (it needlessly complicated Tapestry 4). Given how loosely connected Tapestry 5 pages are from each other, there doesn't seem to be an advantage to doing so ... and certainly, in terms of memory utilization, there is a significant down side, were it even possible.
You can run a Tapestry 4 app and a Tapestry 5 app side-by-side (the package names are different, for just this reason), but they know nothing of each other, and can't interact directly. This is just like the way you could have a single WAR with multiple servlets; the different applications can only communicate via URLs, or shared state in the HttpSession.
Integration with existing applications
Contents
You may have an existing JSP (or Struts, Spring MVC, etc.) application that you want to migrate to Tapestry. It's quite common to do this in stages, moving some functionality into Tapestry and leaving other parts, initially, in the other system. You may need to prevent Tapestry from handling certain requests.
How do I make a form on a JSP submit into Tapestry?
Tapestry's Form component does a lot of work while an HTML form is rendering to store all the information needed to handle the form submission in a later request; this is all very specific to Tapestry and the particular construction of your pages and forms; it can't be reproduced from a JSP.
Fortunately, that isn't necessary: you can have a standard HTML Form submit to a Tapestry page, you just don't get to use all of Tapestry's built in conversion and validation logic.
All you need to know is how Tapestry converts page class names to page names (that appear in the URL). It's basically a matter of stripping off the root-package.pages prefix from the fully qualified class name. So, for example, if you are building a login screen as a JSP, you might want to have a Tapestry page to receive the user name and password. Let's assume the Tapestry page class is com.example.myapp.pages.LoginForm; the page name will be loginform (although, since Tapestry is case insensitive, LoginForm would work just as well), and the URL will be /loginform.
<form method="post" action="/loginform"> <input type="text" value="userName"/> <br/> <input type="password" value="password"/> <br/> <input type="submit" value="Login"/> </form>
On the Tapestry side, we can expect that the LoginForm page will be activated; this means that its activate event handler will be invoked. We can leverage this, and Tapestry's RequestParameter annotation:
public class LoginForm
{
void onActivate(@RequestParameter("userName") String userName, @RequestParameter("password") String password)
{
// Validate and store credentials, etc.
}
}
The RequestParameter annotation extracts the named query parameter from the request, coerces its type from String to the parameter type (here, also String) and passes it into the method.
How do I share information between a JSP application and the Tapestry application?
From the servlet container's point of view, there's no difference between a servlet, a JSP, and an entire Tapestry application. They all share the same ServletContext, and (once created), the same HttpSession.
On the Tapestry side, it is very easy to read and write session attributes:
public class ShowSearchResults
{
@SessionAttribute
private SearchResults searchResults;
}
Reading the instance variable searchResults is instrumented to instead read the corresponding HttpSession attribute named "searchResults". You can also specify the value attribute of the SessionAttribute annotation to override the default attribute name.
Writing to the field causes the corresponding HttpSession attribute to be modified.
The session is automatically created as needed.
How do I put the Tapestry application inside a folder, to avoid conflicts?
Support for this was added in 5.3; see the notes on the configuration page.
—