Wiley Professional Portal Development with Open Source Tools
Contents
1. lt portlet app gt Building a Portlet 32 Now let s work through a complete example of a portlet This portlet is a little more complex than our previous example but itis not as involved as the portlets found in Chapter 9 which covers building portlet applications The first thing to do in building the portlet is to build the portlet class Most portlet classes simply extend GenericPortlet as shown in the following code This class demonstrates a basic search portlet using the Jakarta Lucene search API yf package org opensourceportals samples import java io IOException import javax portlet ActionRequest import javax portlet ActionResponse import javax portlet GenericPortlet import javax portlet PortletException import javax portlet PortletMode import javax portlet PortletPreferences import javax portlet PortletRequestDispatcher import javax portlet RenderRequest import javax portlet RenderResponse import javax portlet ValidatorException import org apache lucene analysis Analyzer import org apache lucene analysis standard StandardAnalyzer import org apache lucene queryParser ParseException import org apache lucene queryParser QueryParser import org apache lucene search Hits import org apache lucene search IndexSearcher import org apache lucene search Query import org apache lucene search Searcher per author Clay Richardson Lyi public class LucenePortlet e2. 04 469513 Ch01 gqxd 1 16 04 11 04 AM Page 3 cb The Java Portlet API JSR 168 This chapter discusses the centerpiece of portal development the Java Portlet API Java Specification Request 168 JSR 168 The chapter explains the concepts in the specification explaining how they fit into portal architectures to enable the developer to be an effective portal developer Portlet Fundamentals A portal server handles client requests Much like a Web application server has a Web container to manage running Web components servlets JSPs filters and so on a portal has a portlet con tainer to manage running portlets Note that most Web application servers such as Tomcat have additional features beyond the Web container management console user databases and so on including some specialized Web applications an administration Web application for example Portals are expected to follow a similar pattern providing higher level functionality wrapped around the portlet container that adheres to the specification enabling portlet applications to be portable just as Web applications are The Portlet API is an extension to the servlet specification which means that a portlet container is also by definition a Web container Figure 1 1 demonstrates the Portal stack which indicates how the various parts build upon each other to provide a portal server 04 469513 Ch01 gqxd 1 16 04 11 04 AM Page 4 cb Chapter 1 Web Browser Web Bro
3. a servlet and is called once when the container disposes of the portlet When an exception is thrown in the portlet init method the destroy method is guaranteed not to be called Therefore if resources are created in the init method prior to the exception being thrown the developer cannot expect the destroy method to clean them up and must handle them in the exception s catch block Portlet Runtime States When a portlet is running it has an associated Preferences object that allows for customization of the portlet The initial values of the preferences are those specified in the deployment descriptor but the portlet has full programmatic access to its preferences When a portlet is placed on a page a Preferences object is related to it The pairing of the portlet and a Preferences object on a page is known as a portlet window A page can contain many of the same portlet windows within its display Before you start wondering why all of these Preferences objects are necessary realize that this is pro viding the capability to perform a major features of a portal customization While the initial portlet Preferences object is great for specifying the configuration and runtime state of the portlet it is 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 9 cb The Java Portlet API JSR 168 necessary to tweak that state to handle customized views of the portlet For example say you have an employee directory portlet Obviously it would
4. gt index location lt name gt lt value gt opt lucene index lt value gt lt read only gt true lt read only gt lt preference gt lt preference gt lt name gt sites to crawl lt name gt lt value gt http jakarta apache org lt value gt lt value gt http java sun com lt value gt lt value gt http onjava com lt value gt lt preference gt lt preference gt lt name gt crawl depth lt name gt lt value gt 2 lt value gt preterence gt lt preferences validator gt com opensourceportals validator CrawlValidator lt preferences validator gt lt portlet preferences gt Here we have the relevant security references for the portlet The role name element specifies the parameter that should be passed to the request isUserInRole String roleName method The role link is the role defined in the portlet application s web xm1 into which the user should be mapped lt security role ref gt lt role name gt ADMIN lt role name gt lt role link gt administrator lt role link gt lt security role ref gt This closes the definition of the portlet This can be repeated as many times as necessary to define all of the portlets within your portlet application Of course each of your portlets must have a unique name within this portlet application lt portlet gt 30 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 31 cb The Java Portlet API JSR 168 Portlet Customization Declarations This defines a custo
5. it Use this to style an unselected menu item that has menu items nested underneath it Use this to style a selected menu item that has menu items nested underneath it This styles text that is used to describe the menu This is used for the menu caption By using these styles portlet developers ensure that their portlets can be reused in many portlet applica tions and be consistent with WSRP In addition it enables developers to apply skins from other port let applications to their portlet 23 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 24 cb Chapter 1 User Information Attributes User attributes are used to create a profile for a user They are meant to be standardized on the World Wide Web Consortium s W3C Platform for Privacy Preferences P3P 1 0 www w3 org TR P3P These attributes are also consistent with the efforts of the OASIS Web Services for Remote Portals stan dard The following table lists the user attributes and their descriptions Attribute Name Description user bdate The user s birth date expressed in milliseconds from January 1 1970 at 00 00 00 Greenwich Mean Time user gender The sex of the user user employer The name of the user s employer user department The department in which the user works user jobtitle The user s job title user name prefix The prefix of the user s name Mr Mrs Dr etc user name given The user s given name Jennifer Alicia etc us
6. of a Web application it is logical that it could contain other Web application components Portlets can use JSPs and servlets to implement their functionality This capability is discussed later in the chapter Portal Interactions It makes sense to show how a typical portal interaction occurs before diving into details about how portlets can render themselves with JSPs and servlets Figure 1 2 demonstrates the chain of events that occur inside a portal to manage a typical client request Inside a portal is a Portlet API compliant portlet container that manages the runtime state of portlets The container evaluates those portlets into fragments either by making requests of the portlet or by taking a fragment from cache Then the container hands the fragments to the portal server that manages aggregat ing them into portal pages Now that you have looked at portals portlets and portal containers at a high level itis time to dig into the specifics about how to build portlets rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 7 cb The Java Portlet API JSR 168 Figure 1 2 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 8 cb Chapter 1 The Portlet Interface and the GenericPortlet The Portlet interface defines the behaviors that all portlets must implement Typically you would pre fer to extend the GenericPortlet class to build a portlet becaus
7. portlet icon label portlet dlg icon label portlet form field label portlet form field portlet menu portlet menu item portlet menu item selected portlet menu item hover portlet menu item hover selected portlet menu cascade item portlet menu cascade item selected portlet menu description portlet menu caption This style is used for highlighting a particular set of cells for the user If you have subheadings in your table that you need to distinguish from your table header you use this style If you include a footer to your table this style would be used for those cells This style is used for things that do not fit in the other style definitions This is to style the label for the whole form such as User Regis tration Form This is for the text that a user enters into an input field This is for the text that appears on the face of a button This styles text next to an application specific icon such as Export This styles text next to a standard icon such as Cancel This styles text that separates form fields such as radio buttons This is used for labels of checkboxes but not for input fields This styles the menu itself e g color Use this to style an ordinary menu item that is not selected This is used to style an item that has been selected Use this to style an ordinary menu item when the mouse hovers over it This is used to style a selected item when the mouse hovers over
8. portlets and handles requests from the portal by invoking portlets inside the container Although this is not an all encompassing list it provides the basic terms that are used repeatedly in this chapter Fragments are not allowed to use certain tags from their respective markup lan guages These tags include html title head body base frameset frame link meta and style Use of these tags will invalidate the entire fragment This is particularly important to developers like us who have been abusing the forgiving nature of browsers until now Portlets and Servlets As mentioned before the Portlet API is an extension to the Servlet API Therefore there are both similar ities and differences between the components It is important to understand these distinctions in order to understand why there is a portlet specification and break habits wrought from using their similar servlet sisters The similarities between portlets and servlets are as follows A Portlets and servlets are both Java 2 Enterprise Edition J2EE Web components Q Both are managed by containers which control their interactions and life cycle Q Each generates dynamic Web content via a request response paradigm rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 6 cb Chapter 1 The differences between portlets and servlets are as follows Portlets generate fragments whereas servlets generate complete documents Unlike servlets p
9. require certain preferences to get it running However when that employee directory portlet is embedded on a Finance Department home page it should not only have a customized look and feel but also have preferences related to the fact that it is on that page such as showing only Finance Department employees Portlet Request Handling Two types of requests can be issued against a portlet action requests and render requests Not coinci dentally these requests have their accompanying URL types action URLs and render URLs An action URL targets the portlet s processAction method while the render URL targets its render method There Can Be Only One If a client request is an action request then it can target only one portlet which must be executed first No other action requests can be performed on the remaining portlets only render requests Figure 1 3 illustrates how a portal container would manage an action request As you can see the portlet container will execute processAction on the targeted portlet waiting until it finishes before it executes render on the rest of the portlets on the page The calling of the render method on the remaining portlets can be done in any order and can be done in parallel The processAction method is responsible for changing state on the given portlet while the render method is responsible for generating the appropriate presentation content of the portlet Therefore it is logical that a u
10. required in the XML Schema for the portlet xm1 and reusable standards compliant lt user attribute gt lt description gt P3P attribute for work e mail address lt description gt lt name gt user business info online email lt name gt lt user attribute gt This is the security constraint for this portlet application It lists the name of the portlet ExamplePortlet and also specifies a user data constraint of INTEGRAL User data constraints define the guarantees specify ing how the portlet communicates with the user Three values are allowed here NONE INTEGRAL and CONFIDENTIAL NONE means that there are no guarantees about the transmission of data between the portlet application and the user INTEGRAL specifies that the data must be checked to ensure that it has not been manipulated no added or removed information from the message CONFIDENTIAL requires that the data cannot be read by anyone other than the user Typically Secure Sockets Layer SSL is used to pro vide both INTEGRAL and CONFIDENTIAL constraints lt security constraint gt lt portlet collection gt lt portlet name gt ExamplePortlet lt portlet name gt lt portlet collection gt lt user data constraint gt lt transport guarantee gt INTEGRAL lt transport guarantee gt lt user data constraint gt lt security constraint gt 31 rn 04 46951 3 Ch01 qxd 1 16 04 11 04 AM Page 32 cb Chapter 1 This defines the end of the portlet application
11. to the portal in which it is running through the PortalContext object Calling the getPortalContext method of the PortletRequest object will return the PortalContext The PortalContext provides the following The name of the portal through getPortalInfo Portal properties through getProperty and getPropertyNames a a Q The supported portlet modes through getSupportedPortletModes a The supported window states through getSupportedWindowStates Portlet Preferences In order to perform customization or personalization of your portlet you need some way to vary certain parameters of the portlet These are called portlet preferences The classic portlet example is the weather 16 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 17 cb The Java Portlet API JSR 168 portlet and following that example you could have a preference called cities with values represent ing the zip codes of the cities for which you want the weather Note that preferences are only meant for configuring the portlet so maintaining the list of all cities available in a preference would be an inappro priate use of preferences Thinking of them in an object oriented programming sense they would be attributes of the portlet itself Preferences are manipulated through an object that implements PortletPreferences All preference values are stored as String arrays so you would not have the capability to store complex objects as you do with request or sessi
12. 01 gxd 1 16 04 11 04 AM Page 36 cb Chapter 1 package org opensourceportals validator import java io File import java util ArrayList import java util List import javax portlet PortletPreferences import javax portlet PreferencesValidator import javax portlet ValidatorException per author Clay Richardson e public class LuceneValidator implements PreferencesValidator In order to create a validator we implement the javax portlet PreferencesValidator interface If it fails validation we throw a ValidatorException We declare our LuceneValidator by extending PreferencesValidator public void validate PortletPreferences preferences throws ValidatorException List problems new ArrayList String indexPath preferences getValue indexPath null Does the preference even exist if indexPath null problems add indexPath throw new ValidatorException indexPath preference doesn t exist problems else Let s check to see if the index is actually there The segments file is a good file to key off of File index new File indexPath segments if index exists problems add indexPath throw new ValidatorException The index doesn t exist problems The LuceneValidator checks first to see if the indexPath preference is actually set to some value If it is set then it determines whether the specified directory contains a segments file which w
13. 4 11 04 AM Page 25 cb The Java Portlet API JSR 168 Attribute Name Description user home info telecom The user s home telephone local number for example telephone number 555 1111 etc user home info telecom The user s home telephone extension if they have one for telephone ext example 745 2918 etc user home info telecom Comments about the user s home telephone optional telephone comment user home info telecom The international access code for the user s home fax for example fax intcode 44 for the United Kingdom and 1 for the United States user home info telecom The user s home fax area code 703 818 etc fax loccode user home info telecom The user s home fax local number 555 1111 etc fax number user home info telecom The user s home fax extension if they have one 745 2918 etc fax ext user home info telecom Comments about the user s home fax optional fax comment user home info telecom The international access code for the user s home mobile mobile intcode telephone for example 44 for the United Kingdom and 1 for the United States user home info telecom The user s home mobile telephone area code for example 703 mobile loccode 818 etc user home info telecom The user s home mobile telephone local number 555 1111 etc mobile number user home info telecom The user s home mobile telephone extension if they have one mobile ext for example 745 291
14. 8 etc user home info telecom Comments about the user s home mobile telephone optional mobile comment user home info telecom The international access code for the user s home pager for pager intcode example 44 for the United Kingdom and 1 for the United States user home info telecom The user s home pager area code for example 703 818 etc pager loccode user home info telecom The user s home pager local number for example 555 1111 etc pager number user home info telecom The user s home pager extension if they have one for example pager ext 745 2918 etc user home info telecom Comments about the user s home pager optional pager comment Table continued on following page 25 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 26 cb Chapter 1 Attribute Name Description user home info online email The user s home e mail address user home info online uri The user s home Web page user business info The name that should appear at the top of a work address for postal name example Sun Microsystems or XYZ Inc etc user business info The street address of the user s work for example 1600 Penn postal street sylvania Avenue or 742 Evergreen Terrace user business info The postal city of the user s work for example Haymarket postal city Manassas etc user business info The state or province used in the user s work address for postal stateprov example Virginia Bri
15. O encodeRedirectURL encodeRedirectUrl setContentType setContentLength setLocale sendRedirect sendError addCookie setDateHeader addDateHeader setHeader addHeader setIntHeader addIntHeader setStatus containsHeader The encode methods always return null and containsHeader always returns false but the remainder will simply do nothing This could be a source of great frustration if you are not careful as a developer because it simply will not work and will provide no notice The Java Portlet Specification recommends against using the forward method of the RequestDispatcher of an included servlet or JSP While this doesn t seem like a big deal note that Apache s Struts Framework uses the RequestDispatcher forward method in its ActionServlet Given the popularity of Struts as a Web application framework this could make a significant impact on portal integration in many enter prises This is not to say that it may not work anyway but it is non deterministic and should be carefully examined in your circumstance and tested with your portal implementation Portlet Application Structure Portlet applications are structured just like Web applications in that they have the following features a a Can contain servlets JSPs Java classes Java archives JAR files and other static files Are self contained all things in the Web application are packaged together in a common root Have a WEB INF classes directory t
16. Q store This stores the preferences Because this can only be done from within processAction it will throw an I11egalStateException if it is done from within a render invocation The method will also throw a ValidatorException if it fails validation Q getMap This returns a Map of the preferences The Map consists of String keys and a String for values This map is also immutable cannot be changed Note two important things to understand about the store method First itis an atomic transaction Therefore all of the changes must succeed or none of them will succeed This is critical to understand if you have an enormous preference list for your portlet and you don t do a tremendous amount of validation of the input Second you could get stung by concurrent writes to the preference store The critical message here is that you should view your preferences as one distinct entity and not a collection of independent parameters accessible through a common interface 17 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 18 cb Chapter 1 The following code is an example of retrieving and setting preferences Bey A PortletPreferences myPrefs request getPreferences String cities myPrefs getValues cities new String 20112 90210 for int i 0 i lt cities length i System out println cities 1 String newCities new String 20169 22124 myPrefs setValues cities newC
17. RenderParameter success The update was successful catch ValidatorException ve System out println Preferences did not validate aRes setRenderParameter success The preferences did not validate aRes setRenderParameter index prefs getValue indexPath Otherwise we want to pull the preference and pass it as a render parameter to our portlet y else PortletPreferences prefs aReq getPreferences aRes setRenderParameter index prefs getValue indexPath In EDIT mode we set the index portlet preference based on the parameters submitted from the searchEdit jsp If there is no Submit parameter we know that it is the initial view of the EDIT page and therefore we want to retrieve the index preference The LucenePortlet uses a common method of building portlets in that it delegates its user interface rendering to JSPs through a PortletRequestDispatcher Two major actions are processed by the portlet One in VIEW mode handles searching the Lucene index and the other in EDIT mode allows modification of the Lucene index location through a portlet preference called indexPath We want to determine whether the indexPath preference is actually pointed at a Lucene index so we will implement our own PreferencesValidator called LuceneValidator which is shown in the following code This class demonstrates a basic validator E 35 04 469513 Ch
18. appending parameters to an HTTP query string is not correct as it may omit portal specific references that should be included in the URL Logically we now need a page to view the results of our search The following code provides a search results page lt page import java util org apache lucene search java text gt lt page import org apache lucene document gt lt jsp useBean id hits scope request type org apache lucene search Hits gt lt String shaded silver DecimalFormat form new DecimalFormat gt lt p gt lt i gt lt b gt lt hits length gt lt b gt lt i gt Documents match your request lt p gt lt center gt lt table width 100 gt lt for int a Mp 2 lt 295 16 a Document doc hits doc i we 2 amp 2 es shaded silver 37 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 38 cb Chapter 1 else shaded white gt lt tr bgcolor lt shaded gt gt Zico lt i 1 startRow gt lt font color medi lt form format hits score i 100 gt lt font gt lt a href lt doc get url gt gt lt doc get title gt lt a gt lt br gt lt doc get summary 3 gt lt td gt MEES lt gt lt table gt lt center gt As you can see this is a simplistic search result page providing only twenty five search results and no paging capability Finally the following code provides the portlet applicatio
19. ctively The ActionURL provides the capability to issue action requests on the portal to do things such as change portlet mode change window state submit a form and so on The RenderURL provides the capability to skip the portlet s processAction method and merely invoke the render method passing render parameters to control presentation 14 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 15 cb The Java Portlet API JSR 168 Portlet developers should use the Port let URL objects or their accompanying tag libraries instead of directly manipulating HTTP query strings The corollary to this is that developers should not use GET in HTML forms This is because portals may encode internal state parameters in the PortletURL You will find several methods of the Port letURL interface interesting Q setSecure provides the capability to specify whether the URL should use HTTPS or not If it is not used it continues with whatever the current request specified Therefore you do not have to specify it repeatedly OQ setWindowState enables you to change the window state of the portlet Ql addParameter adds parameters to the URL Q tostring provides a string representation of the URL Note that it is not guaranteed to be a valid URL as the portal may use tokens for URL rewriting Q setPortletMode enables you to set the portlet s mode Portlet Modes A portlet mode represents a functional state of a portlet This is u
20. e ResourceBundle contains certain fields required by the specification including title short title and keywords A ResourceBundle allows for easier localization of your portlet application You can specify the ResourceBundle inline in the portlet application deployment descriptor as follows lt portlet gt lt portlet info gt lt title gt Homer s D oh a Day Portlet lt title gt lt short title gt doh lt short title gt lt keywords gt Simpsons Homer Simpson Entertainment lt keywords gt lt portlet info gt lt portlet gt Alternatively you can specify a reference to a ResourceBundle this way lt portlet gt lt portlet info gt lt resource bundle gt com somedomainname HomerPortlet lt resource bundle gt lt portlet info gt lt portlet gt Whichever method you use the first is better mostly for applications with minimal localization require ments the net effect for the developer is the same These properties are always created in a Resource Bundle and made available through the Port letConfig object PortletURL When building portlet content itis necessary to build URLs that provide the capability to call the portal This is the foundation of making the portal interactive In order to allow for the proper creation of a PortletURL there are two implementations ActionURL and RenderURL Both of these are created from the RequestResponse interface using the createActionURL and createResponseURL methods respe
21. e it provides structures for providing all of the typical portlet implementation methods not simply the required ones Portlet Life Cycle Much like servlets a portlet s life cycle is managed by the container and has an init method that is used to manage the initialization requirements creating resources configuring and so on Portlets are not guaranteed to be loaded until needed unless you configure the container to load them on startup The init method takes an object that implements the PortletConfig interface which manages initial ization parameters and the portlet s ResourceBundle This object can be used to get a reference to the object that implements the PortletContext interface Portlet developers don t typically spend a lot of time worrying about the intricacies of portlet container initialization exceptions because generally they are thrown and the developer reacts to them debug ging the circumstance that led to the exception and correcting it if appropriate However it is worth noting that an UnavailableException is able to specify a time for which the portlet will be unavail able This could be both useful keeping the portlet container from continuously trying to load the port let and aggravating Why isn t the portlet container reloading my portlet to a developer The destroy method provides the opportunity to clean up resources that were established in the init method This is analogous to the destroy method in
22. ecify which types of markup are available for a given portlet mode Additional information on configuring portal modes is presented in a later section Portlet Application Deployment Descriptor 15 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 16 cb Chapter 1 Window States The window state indicates to the portlet how much space is being allocated to it This enables the port let to modify its rendering to suit that window state The following table contains the window states specified by the Portlet API State Definition NORMAL The portlet will share the screen with other portlets This means that the port let should limit its markup MINIMIZED The portlet should provide little or no output MAXIMIZED The portlet doesn t share the screen with other portlets thus the portlet is not limited in its markup Much like portlet modes a portal can define custom window states which must also be configured in the portlet deployment descriptor Portlet Context PortletContext is a wrapper object for your portlet application There is one PortletContext object per portlet application The PortletContext provides the following A Accesses initialization variables Gets and sets context attributes Logs events Gets application resources such as images XML files and so on Oo 0 0 0O Obtains a request dispatcher to leverage servlets and JSPs in the portlet Portal Context A portlet can get a reference
23. ents the title that will be displayed on the portlet The short title provides an abbreviated way of referencing the portlet such as in a management console Similarly the keywords are meant to provide context about the subject of the portlet This portlet information could have also been referenced in a ResourceBundle with only the name of the ResourceBundle specified here 29 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 30 cb Chapter 1 lt portlet info gt lt title gt Pre configured title lt title gt lt short title gt Example lt short title gt lt keywords gt JSR 168 Portlet API Example Simple lt keywords gt lt portlet info gt This section shows the portlet preferences Of course the preferences you define must be unique The index location preference is read only so it cannot be changed programmatically instead it must be changed here The second preference sites to crawl shows how multiple values can be specified for a preference The last preference crawl depth represents a number that must be converted through Integer parseInt because preferences are all retrieved as either a String or a String array The preferences validator element specifies a class that is used to validate these portlet preferences In this case the validator would confirm that the sites to crawl are valid and that the crawl depth is less than five to keep the crawling time down lt portlet preferences gt lt preference gt lt name
24. er client per portlet and cannot be shared across client requests Of course a developer could implement his or her own portlet managed cache in the render method storing some commonly requested data in the PortletContext 04 469513 Ch01 qxd 1 16 04 11 04 AM Page 10 cb Chapter 1 So Figure 1 3 ActionRequest As previously mentioned in the discussion of portlet request handling action requests handle changing the state of a portlet based on the action request parameters This is done using the processAction method which takes an ActionRequest and ActionResponse object as parameters The ActionRequest object similar to a ServletRequest object provides the following Q The action request parameters Q The portlet mode 10 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 11 cb The Java Portlet API JSR 168 The portlet session The window state The portlet preferences object COoveo ovo The portal context To change the portlet mode or window state you call the appropriate method on the Act ionResponse object The change becomes evident when the render method is called subsequent to the end of process ing in the processAction method You can also pass render parameters using the Act ionResponse object RenderRequest RenderRequests generate a fragment from the portlet s current state The RenderRequest object pro vides access to the following The render request parameters The portlet mode The portlet sessio
25. er name family The user s last name Richardson Smith Avondolio etc user name middle The user s middle name Anne Clay Trent etc user name suffix The suffix following a user s name Sr Jr III etc user name nickname A user s nickname Mojo PAB BP etc user home info postal The name that should appear at the top of a home address for name example The Richardsons or William C Richardson user home info postal The street address of the user s home 1600 Pennsylvania street Avenue or 742 Evergreen Terrace user home info postal The postal city of the user s home Haymarket Manassas etc city user home info postal The state or province used in the user s home address Virginia stateprov British Columbia etc user home info postal The user s home zip code 90210 etc postalcode user home info postal The user s home country United States of America Canada etc country user home info postal A subheading in the address block like Finance Department organization which doesn t make a lot of sense for a home address but is included for completeness user home info telecom The international access code for the user s home telephone for telephone intcode example 44 for the United Kingdom and 1 for the United States user home info telecom The user s home telephone area code for example 703 818 etc telephone loccode 24 rn 04 469513 Ch01 gxd 1 16 0
26. ero it would be just the opposite never cached lt expiration cache gt 1 lt expiration cache gt This next section declares the supported portlet modes and mime types For each mime type the sup ported portlet modes are listed Wild cards are acceptable in describing a mime type For example all text based mime types could be specified as text and all mime types could be expressed as In this case the portlet supports traditional HTML with three different modes available VIEW EDIT and HELP However it supports the VIEW mode only when the content type is the Wireless Markup Language WML Each of these definitions must be unique that is you cannot define multiple sup ports blocks for the same MIME type lt supports gt lt mime type gt text html lt mime type gt lt portlet mode gt view lt portlet mode gt lt portlet mode gt edit lt portlet mode gt lt portlet mode gt help lt portlet mode gt lt supports gt lt supports gt lt mime type gt text wml lt mime type gt lt portlet mode gt view lt portlet mode gt lt supports gt This portlet provides only one Locale English for its internationalization support It could support many locales and it would list them all here For more information examine Java s internationalization support lt supported locale gt EN lt supported locale gt This element lt portlet info gt provides the metadata about the portlet The title element repres
27. esponse response throws PortletException IOException PortletMode mode new PortletMode request getParameter mode response setPortletMode mode Finally we specify overriding the get Title method allowing for more complex logic in rendering the title such as displaying the current date rather than displaying the static title declared in the deploy ment descriptor We also handle the processAction method which is responsible for the behavior in response to an ActionRequest The preceding code shows a basic implementation of a portlet by writing a class that extends Generic Portlet This portlet doesn t do much beyond dispatch to other JSPs based on its mode and set its name programmatically but you see the crux of implementing a portlet 13 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 14 cb Chapter 1 Other Elements of the Java Portlet API Now that you have examined the high level concepts of the Portlet API this section addresses the lower level components within the specification providing a portlet developer s perspective on the internals of the specification highlighting important concepts and potential pitfalls PortletConfig When a portlet is initialized it needs access to the initialization parameters and other configuration infor mation The PortletConfig object provides these In addition to init parameters the PortletConfig object can also expose a ResourceBundle for the portlet Th
28. et a PortletRequestDispatcher prd from your PortletContext portContext Then you pass your RenderRequest req and your RenderResponse resp as parameters to the include method of the PortletRequestDispatcher prd Similarly we can call a servlet by its declared name in the Web application deployment descriptor also known as web xm1 For example we might have specified a servlet such as the following in the web xm1 lt servlet gt lt servlet name gt chart lt servlet name gt lt servlet class gt org opensourceportals ChartServlet lt servlet class gt lt load on startup gt 0 lt load on startup gt lt servlet gt Because we have named our servlet chart we can specify it as follows String reqName chart PortletRequestDispatcher prd portContext getNamedDispatcher reqName prd include req resp 19 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 20 cb Chapter 1 This time we used the getNamedDispatcher method with the name of our servlet in order to get a PortletRequestDispatcher This is another important point to consider if you choose to do the following String reqPath calView jsp user Jennifer PortletRequestDispatcher prd portContext getRequestDispatcher reqPath prd include req resp Because the parameter user is specified in the query string it will take precedence over any other ren der parameters named user being passed to the JSP You probably will not encounter this problem but
29. ionResponse aRes throws PortletException IOException PortletMode mode new PortletMode aReq getParameter mode aRes setPortletMode mode if mode equals PortletMode VIEW PortletPreferences prefs aReq getPreferences String indexPath prefs getValue indexPath null Searcher searcher new IndexSearcher indexPath Analyzer analyzer new StandardAnalyzer StringBuffer queryBuffer new StringBuffer String searchString aReq getParameter searchString if searchString null queryBuffer append searchString String line queryBuffer toString Ese Query query QueryParser parse line contents analyzer Hits hits searcher search query aReq setAttribute hits hits catch ParseException pe pe printStackTrace else aRes setRenderParameter queryMode begin Our processAction behavior depends on the portlet s mode If we have a searchString object then we use it to query Lucene If not we set a render parameter else if mode equals PortletMode EDIT If the Submit button is passed as a parameter then we 34 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 35 cb The Java Portlet API JSR 168 know it came from a form E if aReq getParameter Submit null PortletPreferences prefs aReq getPreferences String indexPath aReq getParameter indexPath prefs setValue indexPath indexPath ey prefs store aRes set
30. it is something to keep in the back of your mind in case you run into crazy behaviors specifying a query string takes precedence over other parameters There are restrictions on the use of HttpServletRequest These methods are not available to the included servlet or JSP getProtocol getRemoteAddr getRemoteHost getRealPath getRequestURL setCharacterEncoding getContentType getInputStream getReader a a a a a O getCharacterEncoding a a a a a getContentLength These methods will all return null getContentLength returns zero if invoked from a servlet or JSP that has been included by a Port letRequestDispatcher Depending on how you create your PortletRequestDispatcher you may not have access to other methods These additional methods are not available to servlets or JSPs accessed from a Port letRequestDispatcher created by calling getNamedDispatcher getPathInfo getPathTranslated getServletPath getRequestURI Oooo ovo getQueryString The reason why the preceding methods would be unavailable through getNamedDispatcher is pretty simple Because you didn t use a path for your request there is no data with which these fields can be 20 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 21 cb The Java Portlet API JSR 168 populated Likewise HttpServletResponse has restrictions on what is accessible The unavailable methods of HttpServletResponse are DO CoocovocevovcevocvocvoUOAOUOUOUUOC D
31. ities myPrefs store catch ValidatorException ve System out println Preferences did not validate catch UnmodifiableException ume System out println The preference is not modifiable catch IllegalStateException ise System out println You cannot be in render Developers can define custom classes to provide validation of preferences These classes implement the PreferencesValidator interface and must provide their validation capability in a thread safe manner Implementing a PreferencesValidator is very simple There is only one method validate which takes a PortletPreferences object and returns nothing Simply throw a Validator of the values doesn t meet the logic you define Sessions Because portals are built upon the request response paradigm and predominantly upon HTTP there has to be some mechanism available to maintain state across invocations For example it isn t sensible to authenticate users with every request There are several techniques to manage sessions with cookies and URL rewriting being two of the most popular in Web applications cookies are used under the hood by many servlet containers to implement the HTTPSession 18 Exception if any Sessions are critical to portlet development but there are many ways to implement them so the Portlet API provides the PortletSession interface When a client makes a request the server sends a session identifier in the response If the clien
32. m portlet mode called My_MODE Of course whenever an application defines a cus tom portlet mode it must not only be available through the targeted portal server but also needs to have portlets that actually use the mode while programming defensively enough to avoid breaking in unsup ported portal servers lt custom portlet mode gt lt description xml lang EN gt Custom portlet mode MY_MODE lt description gt lt portlet mode gt MY_MODE lt portlet mode gt lt custom portlet mode gt LEFT SIDE is defined here as a custom window state Just as with custom portlet modes custom win dow states can cause problems with your application s portability In addition like custom portlet modes you can define multiples in the same application but they must have unique names lt custom window state gt lt description xml lang EN gt Docked into the left side lt description gt lt window state gt LEFT SIDE lt window state gt lt custom window state gt User Attributes and Security Constraints The following code defines a user attribute called user business info online email that refers to a user s business e mail address Typically these attributes are mapping from the portal server s per sonalization database which is why using standard names can ease the integration of user attributes Developers should use user attributes from the W3C P3P standard as specified in the Portlet API This should ensure that they are unique as
33. n The window state Oooo o The portlet preferences object There is also an accompanying RenderResponse method which provides the vehicle needed to render content You can call getOutputStream or getWriter as you do ina servlet or you can dispatch the content generation to a servlet or JSP There is more detail on this technique later in the chapter in the section Calling JSPs and Servlets The request and response objects are not thread safe This means that a developer should avoid sharing references to them with other threads of execution Most developers will not run into this problem but remember this tidbit next time you decide to try something unconventional GenericPortlet The GenericPortlet class is an abstract implementation of the Portlet interface This is the most common way most users will write portlets by extending this class The GenericPortlet class extends the render method by setting the portlet title and then calling its own doDispatch method which in turn determines the mode of the Portlet and calls its appropriate method doEdit for EDIT doView for VIEW and so on There is more discussion on portlet modes later The following code describes a class that extends GenericPortlet package org opensourceportals samples import java io IOException import javax portlet ActionRequest import javax portlet ActionResponse 11 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 12 cb Chap
34. n deployment descriptor also known as the portlet xml file lt xml version 1 0 encoding UTF 8 gt lt portlet app gt lt portlet id LucenePortlet gt lt portlet name gt LucenePortlet lt portlet name gt lt display name gt Example Search Portlet with Lucene lt display name gt lt portlet class gt org opensourceportals samples LucenePortlet lt portlet class gt lt expiration cache gt 1 lt expiration cache gt lt supports gt lt mime type gt text html lt mime type gt lt portlet mode gt EDIT lt portlet mode gt lt portlet mode gt VIEW lt portlet mode gt lt portlet mode gt HELP lt portlet mode gt lt supports gt lt portlet info gt lt title gt Example Search Portlet with Lucene lt title gt lt short title gt Lucene Search lt short title gt lt keywords gt Search Lucene lt keywords gt lt portlet info gt lt portlet preferences gt lt preference gt lt name gt indexPath lt name gt lt value gt C lucene index lt value gt A pPrSterences lt preferences validator gt org opensourceportals validator LuceneValidator lt preferences validator gt lt portlet preferences gt lt portlet gt lt portlet app gt The portlet xml file is very basic just like the portlet we just wrote It provides three modes and spec ifies a validator for its preferences 38 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 39 cb The Java Portlet API JSR 168 Summary This chapter focused on explaining the Ja
35. o store standalone classes to be loaded by the application classloader Have a WEB INF lib directory to store Java Archives JAR files to be loaded by the application classloader rn 21 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 22 cb Chapter 1 Q Have a Web application deployment descriptor located at WEB INF web xml Q Are packaged as Web archives WAR files In addition to these features the portlet application contains a portlet application deployment descrip tor located at WEB INF portlet xml This file is described in detail later in this chapter in the section Portlet Application Deployment Descriptor Security Because security is a bigger matter than simply the requirements of the Portlet API we defer the discus sion on security in the Portlet API to Chapter 6 CSS Style Definitions In order to achieve a common and pluggable look and feel for portlets the Java Portlet API defines a set of Cascading Stylesheets CSS styles that portlets should use in rendering their markup By using a standard set of styles portals can support skins customized colors and fonts These styles are meant to coincide with the OASIS Web Services for Remote Portlets standard In order to be complete these style definitions are presented in the following table as specified in Appendix C of the JSR 168 Java Portlet API Attribute Name Description portlet font This is for normal unaccented text used in a portle
36. omments about the user s work pager optional user business info The user s work e mail address online email user business info The user s work Web page online uri As you can see the attributes are a bit repetitive but offer a breadth of options to you as a developer in terms of which user attributes you need to use for your portlet application However it is not sufficient just to use these in your application Your deployment descriptor must declare which of these are used by a portlet application and the deployer needs to map them against the related ones available in the targeted portal server This is where using the standard attributes comes in handy as it will greatly reduce if not eliminate the amount of mapping necessary to deploy your application Presuming you have done all of the appropriate mappings and the section Portlet Application Deployment Descriptor discusses how to do this in your portlet xml you can gain access to user attributes such as the following Map userdata Map String workEmail String request getAttribute user business info online email request getAttribute PortletRequest USER_INFO 27 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 28 cb Chapter 1 You grab a Map of the deployed user attributes by getting that attribute from the PortletRequest Then you simply look up the appropriate value in this case the user s work e mail stored under user bu
37. on attributes nor do you have the advantage of declaring the type as you would with environment entries Therefore if you are storing numbers as preferences you will need to do con versions yourself Specifically the Port letPreferences interface provides the following Qh getNames This returns an Enumeration of the names of the available preferences Qh getValue You pass it the name of the preference you are looking for along with a default value in case it isn t found and it returns the first element of the array of that preference s values Qh getValues You pass it the name of the preference you want and a String array of default val ues and it returns a String array of its values Qh setValue You pass it the name of the preference and the value of that preference and it sets it to a single element String array containing that value This method throws an UnmodifiableException if the preference cannot be modified a setValues You pass it the name of the preference and a String array representing the values for that name and it sets the preference values This method throws an Unmodi fiableException if the preference cannot be modified Ql isReadOnly You pass it the name of a preference and it returns a Boolean indicating whether the preference can be modified Qh reset You pass it the name of the preference and it will restore the default if there is no default it will delete the preference
38. ortlets are not bound directly to a URL Portlets have a more sophisticated request scheme with two types of requests action and render a a a Q Portlets adhere to a standardized set of states and modes that define their operating context and rendering rules Portlets are able to do some things that servlets cannot such as the following Q Portlets have a far more sophisticated mechanism for accessing and persisting configuration information Q Portlets have access to user profile information beyond the basic user and role information pro vided in the servlet specification Q Portlets are able to perform portlet rewriting so as to create links that are independent of the por tal server implementation which have various methods to track session information and so on Q Portlets have two different session scopes in which to store objects application wide and portlet private Portlets lack some servlet features Q Portlets cannot alter HTTP headers or set the response encoding Q Portlets cannot access the URL that the client used to initiate the request on the portal Portlet applications are extended Web applications Therefore both types of applications are deployed in Web archive files WAR and both contain a Web application deployment descriptor web xm1 However a portlet application also contains a portlet application deployment descriptor portlet xml Because a portlet application is an extension
39. ould indicate the presence of a Lucene search engine index This is a perfect example of how you would 36 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 37 cb The Java Portlet API JSR 168 want to use a validator as a mechanism to check a condition that is more complicated than simply pre sent or not present If either of these conditions is false then the LuceneValidator will throw a ValidatorException Now that we have managed the major logical parts of the LucenePortlet we will review the presenta tion aspects of the portlet The following code shows search_view jsp which presents a user interface for searching lt page import javax portlet PortletURL gt lt taglib uri http java sun com portlet prefix portlet gt lt portlet defineObjects gt lt table width 100 border 0 cellspacing 0 cellpadding 0 gt lt er gt lt th gt SEARCH lt th gt lt e lt ET gt lt td gt lt FORM action lt portlet actionURL gt method POST gt lt input type text name searchString gt lt INPUT type submit name Submit value Go gt lt FORM gt lt td gt Efes lt table gt In this JSP we see the first use of the Portlet Tag Library These tags provide access to the portlet from within a JSP The most interesting use here is the actionURL tag which is the proper way of creating links within a portlet application Creating them as was traditionally done in Web applications by
40. s PortletException IOException PortletRequestDispatcher prd getPortletContext getRequestDispatcher help jsp prd include request response e O E E AE O AS This method overrides the doEdit of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is PortletMode VIEW 12 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 13 cb The Java Portlet API JSR 168 lt p gt In this case we will dispatch the method to a JSP located in the portlet root directory called view jsp E protected void doView RenderRequest request RenderResponse response throws PortletException IOException PortletRequestDispatcher prd getPortletContext getRequestDispatcher view jsp prd include request response Similarly we provide the behavior required to render the portlet when it is in its HELP and VIEW modes This method was overriden to specify the title programmatically This may be useful if you are going to have parameters in your title like News on 9 11 2001 Sty protected String getTitle RenderRequest request return Example Portlet This method is the meat of the portlet manipulations of the portlet s state are done through this method For simplicity sake we will parse a param that indicates the portlet mode to which the portlet should be set I E IN E a ZO e public void processAction ActionRequest request ActionR
41. sed by the portlet to determine how to manage a render request That is depending on the mode the portlet will render different markup Portlets are able to change their mode as part of processing action requests In addition a portlet can be configured with different modes available and further restrict its availability based on role The follow ing table describes the standard portlet modes defined in the Portlet API Mode Description VIEW Generates markup visualizing the portlet state and properties Developers implement doView of GenericPortlet to provide this functionality EDIT Produces markup to enable modification of portlet properties Developers implement doEdit of GenericPortlet to provide this functionality HELP Provides help text for the portlet Developers implement doHelp of GenericPortlet to provide this functionality A portal can also provide custom portlet modes Note that this is portal dependent not portlet depen dent Therefore if a portlet implements additional portlet modes they will not be portable between vari ous portlet containers The portlet needs to override the doDispatch method to call the appropriate render method For example if you define a portlet mode called SPECIAL the doDispatch method would call its render method which by convention would be doSpecial Of course because you are implementing the method you could call the method anything you want Also note that you can sp
42. ser can change only one portlet at a time you can only click in one box and that all portlets would have to call render to generate their content again upon the result of the action However this is not to say that all portlets are not able to change at a given time Consider the following common example a portal for The Simpsons One of the portlets allows you to select the given Simpson character whose page you would like to view Other portlets contain character information recent appearances greatest quotes and so on When you select a new character you would change the state of that character selector portlet through the processAction method In that method though you would edit a given shared attribute that specifies which character s page you are on which would cause all of the portlets to render themselves for that character when you invoked their render methods Note one exception to when a portlet s render method is called and that is when the portlet s content is cached The Portlet API allows containers to choose to use a cached copy of the content instead of calling render Portlet containers are not required to provide a cache facility but the spec provides for an expiration cache facility which is configured in the portlet application deployment descriptor The deployer provides an expiration cache element into which the user specifies the number of seconds to cache or 1 for cache that won t expire The cache is p
43. siness info online email User attributes are very important in deploying personalized portlet solutions Be sure to familiarize yourself with these attributes Portlet Tag Library The Portlet JSP Tag Library gives developers the capability to reference Portal components from within a JSP page The following table explains the tags Tag Name Purpose defineObjects This tag declares three objects within the JSP page RenderRequest ren derRequest RenderResponse renderResponse and PortletConfig portletConfig actionURL This tag builds action URLs that point to the current portlet This tag is nested with param tags in order to pass the appropriate parameters in the action URL renderURL This tag builds render URLs It also is nested with param tags namespace This tag provides a unique name based on the current portlet in order to avoid conflicts in variable and function names when all of the portlet frag ments are consolidated into a portal page param This tag gives the name and value of a parameter It is nested inside either the actionURL or renderURL tags Portlet Deployment This section describes the portlet application deployment descriptor portlet xm1 by dissecting a sample and explaining the various sections of the descriptor piece by piece Portlet Application Deployment Descriptor In order to understand the portlet application deployment descriptor well you should examine each part If you have
44. t Size can be overridden using the style attribute with something such as font size large portlet font dim This is for suppressed text essentially text that has been grayed out portlet msg status This is used to represent text that is providing the current state of an operation in project such as Please wait while data loads portlet msg info Use this for informational text such as Reminder your username is your e mail address portlet msg error This styles messages such as An unexpected error occurred please contact the administrator portlet msg alert This is for warnings such as Could not get open database con nection please try again in a couple of minutes portlet msg success This relays messages when the submission was successful such as Your request was submitted portlet section header Use this to render the table or section header portlet section body This is to style the internals of a table cell portlet section When using a technique called banding in which you provide alternate alternate styles in between alternate rows this style provides that capability 22 04 469513 Ch01 qxd 1 16 04 11 04 AM Page 4 The Java Portlet API JSR 168 Description Attribute Name portlet section selected portlet section subheader portlet section footer portlet section text portlet form label portlet form input field portlet form button
45. t wants to join the session the client provides that session identifier with their next request The PortletSession can be used to hold attributes Portletsession operates much like HTTPSession in this regard providing the capability to store key value pairs with arbitrary objects There is one major difference The PortletSession has two different scopes a a PORTLI APPLICATION_SCOPE is very similar to the HTTPSession scope An object placed in this scope is available to all the portlets within the session PORTLET_SCOPE refers to when an object is available to only that portlet ET_SCOPE is unique in that it provides a namespace for the given attribute For example an attribute called city name would be stored in javax portlet p 47 city name 47 is an internally assigned rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 19 cb The Java Portlet API JSR 168 identification number This attribute name prevents namespace collision with other portlets storing their session variables with similar names Despite having a special system for naming its attributes PORTLET_SCOPE doesn t protect its attributes from other Web components In addition the namespace application is done completely under the hood You just call getAttribute and setAttribute specifying PORTLET_SCOPE and the namespace conver sion is done by the PortletSession object To make it even more convenient other Web components can recei
46. ter 1 import javax portlet GenericPortlet import javax portlet PortletException import javax portlet PortletMode import javax portlet PortletRequestDispatcher import javax portlet RenderRequest import javax portlet RenderResponse per author Clay Richardson ExamplePortlet is a basic example of writing a portlet by extending GenericPortlet Sy public class ExamplePortlet extends GenericPortlet This method overrides the doEdit of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is PortletMode EDIT lt p gt In this case we will dispatch the method to a JSP located in the portlet root directory called edit jsp protected void doEdit RenderRequest request RenderResponse response throws PortletException IOException PortletRequestDispatcher prd getPortletContext getRequestDispatcher edit jsp prd include request response w E ae oF We declare our ExamplePortlet having it extend GenericPortlet In here we also override the doEdit method which handles rendering when the portlet is in EDIT mode This method overrides the doHelp of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is PortletMode HELP lt p gt In this case we will dispatch the method to a JSP located in the portlet root directory called help jsp protected void doHelp RenderRequest request RenderResponse response throw
47. tish Columbia etc user business info The user s work zip code for example 90210 postal postalcode user business info The user s work country for example United States of America postal country Canada etc user business info A subheading in the address block like Finance Department postal organization user business info The international access code for the user s work telephone for telecom telephone intcode example 44 for the United Kingdom and 1 for the United States user business info The user s work telephone area code for example 703 818 etc telecom telephone loccode user business info The user s work telephone local number 555 1111 etc telecom telephone number user business info The user s work telephone extension if they have one for telecom telephone ext example 745 2918 etc user business info Comments about the user s work telephone optional telecom telephone comment user business info The international access code for the user s work fax for example telecom fax intcode 44 for the United Kingdom and 1 for the United States user business info The user s work fax area code for example 703 818 etc telecom fax loccode user business info The user s work fax local number for example 555 1111 etc telecom fax number user business info The user s work fax extension if they have one for example telecom fax ext 745 2918 etc user b
48. tletMode VIEW lt p gt In this case we will dispatch the method to a JSP located in the portlet root directory called view jsp E et E NE ee A JE protected void doView RenderRequest request RenderResponse response throws PortletException IOException String queryMode request getParameter queryMode String forwardString searchView jsp if queryMode null forwardString searchResults jsp PortletRequestDispatcher prd getPortletContext getRequestDispatcher forwardString prd include request response 33 rn 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 34 cb Chapter 1 Rendering the VIEW mode depends on whether we passed in a query mode RenderRequest parameter If there is a queryMode parameter we display the results if not we display the search box This method is overriden to specify the title programmatically E protected String getTitle RenderRequest request return Lucene Portlet J This method is the meat of the portlet manipulations of the portlet s state are done through this method ee There are really two types of actions for this portlet depending on which mode we are in In the VIEW mode we have an action that searches a Lucene Index and then places the hits in a request attribute In the EDIT mode we allow users to change the location of the Lucene index public void processAction ActionRequest aReq Act
49. used XML very much you will find this first section unremarkable The only thing worth noting here is that the version attribute is required to determine which version of the specification is in effect lt xml version 1 0 encoding UTF 8 gt lt portlet app xmlns http java sun com xml ns portlet version 1 0 xmlns xsi http ww w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation http java sun com xml ns portlet app_1_0 xsd gt 28 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 29 cb The Java Portlet API JSR 168 Portlet Declarations This is the first part of the declaration of one portlet In this we give it a description a local name a display name and a class name The description and display name are meant to make it more human friendly while the local name and the class actually provide the nuts and bolts required to programmatically load and reference the portlet The local name must of course be unique within the portlet application lt portlet gt lt description gt Example of creating a portlet lt description gt lt portlet name gt ExamplePortlet lt portlet name gt lt display name gt Example Portlet lt display name gt lt portlet class gt org opensourceportals samples ExamplePortlet lt portlet class gt The expiration cache tag represents the number of seconds a portlet is kept in cache The expiration cache value of 1 means that the portlet will always be kept in cache If the value were z
50. usiness info Comments about the user s work fax optional telecom fax comment 26 04 469513 Ch01 qxd 1 16 04 11 04 AM Page 27 The Java Portlet API JSR 168 Attribute Name Description user business info telecom mobile intcode user business info telecom mobile loccode user business info telecom mobile number user business info telecom mobile ext user business info The international access code for the user s work mobile telephone for example 44 for the United Kingdom and 1 for the United States The user s work mobile telephone area code for example 703 818 etc The user s work mobile telephone local number 555 1111 etc The user s work mobile telephone extension if they have one for example 745 2918 etc Comments about the user s work mobile telephone optional telecom mobile comment user business info telecom pager intcode The international access code for the user s work pager for example 44 for the United Kingdom and 1 for the United States user business info telecom pager loccode The user s work pager area code for example 703 818 etc user business info telecom pager number The user s work pager local number for example 555 1111 etc user business info telecom pager ext The user s work pager extension if they have one for example 745 2918 etc user business info telecom pager comment C
51. va Portlet API It provided a basic end to end example of a portlet to demonstrate the API in a practical use However for a more comprehensive chapter on build ing portlet applications see Chapter 9 39 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 40 G
52. ve this feature through the PortletSessionUtil decodeAttribute method by passing the simple attribute name such as city name Calling JSPs and Servlets Because portlet applications are a complementary extension to Web applications there must be a mechanism to include Java Server Pages and servlets in a portlet Upon first examination of the GenericPortlet class many Web developers cringe and think Oh no We are back to the old servlet days of embedding markup However much like servlet developers found using a RequestDispatcher helpful in avoiding the all your eggs in one basket problem of placing all of your markup in your servlet or all of your Java code in a JSP a portlet developer can use a PortletRequestDispatcher When implementing the render method of the Portlet interface or more likely implementing one of the do methods of the GenericPortlet class for example doView doEdit and so on the devel Oper can use a PortletRequestDispatcher as follows String reqPath calView jsp PortletRequestDispatcher prd portContext getRequestDispatcher reqPath prd include req resp In this case we have specified our JSP calView jsp which is located in the root of the portlet applica tion which we refer to with a leading slash You must always start the path with a leading slash and provide a path from the PortletContext root usually the root directory of your portlet application From there you g
53. wser Web Browser Web Container la E S Enterprise Data Enterprise Data Enterprise Data Figure 1 1 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 5 cb The Java Portlet API JSR 168 As you can see the servlet container is the basis for any portal upon which the portlet container exten sion is built Likewise a portal is built on top of that portlet container which manages the portlets required to handle client requests Before describing the relationships between portlets and servlets we should discuss a few of the funda mental definitions related to the Portlet API The following table provides a list of the definitions that are used in this chapter to explain the Portlet API Of course many others will be introduced throughout the chapter but these are the fundamental ones required for an understanding of the chapter Term Definition Portal A Web based application server that aggregates customizes and personalizes content to give a presentation layer to enterprise information systems Portlet A pluggable Web component managed by a portlet container it provides dynamic content as part of an aggregated user interface Fragment The result of executing a portlet a chunk of markup HTML XML and so on that adheres to certain rules see the sidebar Rules for Fragments Portlet Container The runtime environment of a portlet It manages the life cycle of
54. xtends GenericPortlet Hi This method overrides the doEdit of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is PortletMode EDIT lt p gt This mode should always show a form to change the indexPath preference indicating where the index is stored i protected void doEdit E EE E E 04 469513 Ch01 gxd 1 16 04 11 04 AM Page 33 cb The Java Portlet API JSR 168 RenderRequest request RenderResponse response throws PortletException IOException PortletRequestDispatcher prd getPortletContext getRequestDispatcher searchEdit jsp prd include request response We declare our LucenePortlet which extends GenericPortlet When we are in EDIT mode we dis play the searchEdit jsp This method overrides the doHelp of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is PortletMode HELP pe This method provides help information by dispatching the request to help jsp if protected void doHelp RenderRequest request RenderResponse response throws PortletException IOException PortletRequestDispatcher prd getPortletContext getRequestDispatcher help jsp prd include request response And when we are in HELP mode we display help jsp This method overrides the doEdit of GenericPortlet This is called to provide the markup to be rendered when the portlet mode is Por
Download Pdf Manuals
Related Search