The JSR 168 Java Portlet Specification has been around long enough for developers to have learned the most important lessons in practical portlet construction. Drew Varner lists some of his portlet building guidelines in a recent BEA dev2dev article, Guidelines for Writing JSR-168 Portlets:

Sticking to these guidelines will keep your portlets in line with the JSR-168 specification. Adhering to the specification makes it easier to move your portlets among Java portal servers. It also makes it easier to federate your portal's content using WSRP:

• Always Utilize the URL Rewriting APIs for Content in Your Portlet
  While you can use encodeURL() with fully-qualified URLs to reference content outside your portlet, you should do so only if the resource is not accessible by the client. If the client can browse to the resource directly, do not use encodeURL() on the URL.
  
  
• Do Not Append Paths to a Rewritten URL
  The URL passed into RenderRequest's encodeUrl() must be complete before the method call. Portions of the URL cannot be appended after the method call.
  
  
• Qualify Client-side Script Variables and Methods with Namespaces
  It is possible that another portlet in the same page will also have a JavaScript method named [the same as your own JavaScript method] with different logic. The portal framework itself may employ JavaScript methods. The solution to this problem is to namespace methods and top-level variables in your client-side scripts.
  
  
• Ensure Inline Client-side Scripts that Refer to Portlet Resources Follow the Spec
  Client-side scripts often reference external resources (images, movies, external pages) to enhance the user interface... URLs in these client-side scripts must be rewritten according to the JSR-168 specification. These scripts have to be in a JSP or JSR-168 portlet class to call the URL rewriting APIs. They cannot be in a standalone JavaScript (.js) file.
  
  
• Always Declare a Content Type for Portlet Responses
According to the JSR-168 specification, "A portlet must set the content type of the response using the setContentType() method of the RenderResponse interface." [However,] a portlet that does not explicitly set its content type will compile successfully.


• Do Not Send Cookies from Portlets
  If you'd like to persist information on a per-user basis while they are using the portal, you can persist the information as an attribute in the portlet's session. If you'd like to persist information after the user logs out, you can persist it in a data store (file system, database, LDAP, for example).
  
  

When constructing a complex Web site that needs to aggregate information from many sources, in what situations do you follow the Portlet specification, and when do you use a more general Web app framework?