2.6 Portlet deployment

 <  Day Day Up  >  

When a portlet is installed into the portal server, the deployment information is contained in two deployment descriptors. The Web.xml deployment descriptor is used by the WebSphere Application Server to register the portlets being deployed. The application server is not aware of the portlet hierarchy and is simply installing a Web application containing servlets. The portlet.xml deployment descriptor is used by the portal server to retrieve parameters and to set the initial configuration.

When the portlet application is deployed, it is deployed as a Web archive (war), not an enterprise application (ear). When the war file is deployed, the portal server actually creates an associated ear folder in the WebSphere\AppServer\installedApps directory. The new ear folder will contain the original name of the war file with _WPS_PA_191.ear appended to the end of the name of the war file. The last number indicates the order in which the portlet application was installed.

The war file that was deployed is placed into the ear file with a META-INF folder. This folder contains the application.xml deployment descriptor, the ibm-application-ext.xmi and the Manifest.MF files. All these files are generated by the portal server when the application is installed.

Abstract and concrete portlet applications

The portlet.xml deployment descriptor is used by the portal server to identify the abstract and concrete portlet applications you wish to deploy. An abstract portlet application contains one or more abstract portlets. A concrete portlet application contains one or more concrete portlets. The abstract application is used as a foundation for concrete applications. The combination of an abstract application and configuration parameters creates a concrete application. Each portlet.xml may only define a single abstract portlet application. However, any number of concrete applications may be defined based on the single abstract application.

The concrete applications are the applications presented in the portal server administration. They are the actual applications available to the users. This allows the same application to be deployed repeatedly with different parameterization, effectively creating multiple applications.

Figure 2-4. Abstract and Concrete relationship in a single portlet.xml

graphics/02fig04.gif

Certain configuration parameters are set at the abstract level while others are set at the concrete level. As expected, parameters set at the abstract level affect each concrete application. The parameters and configuration information unique to each concrete application are represented in a PortletApplicationSettings object. Parameter and configuration information unique to each portlet are represented in the PortletSettings object. When the portlet is actually placed on a page, it is parameterized by a PortletData object.

When a user logs on and accesses a portlet, it is associated with a session object. This sequence is represented in Figure 2-5 on page 64.

Figure 2-5. Portlet parameterization

graphics/02fig05.gif

2.6.1 web.xml

The web.xml defines the Web application being deployed. This section will detail the required elements of the web.xml when deploying a portlet application. For details on all of the elements of the web.xml deployment descriptor, refer to http://java.sun.com/j2ee/tutorial. Example 2-1 provides an example web.xml document. To keep this section simple, the deployment descriptors will define only a single portlet in the application.

Example 2-1. Simplest web.xml
 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app id="WebApp">    <display-name>HelloWorld</display-name>    <context-param>       <param-name>webmaster</param-name>       <param-value>the webmaster</param-value>    </context-param>    <servlet id="Servlet_1">       <servlet-name>HelloWorldPortlet</servlet-name>       <servlet-class>             com.ibm.itso.ral.portlets.HelloWorldPortlet       </servlet-class>       <init-param>          <param-name> init_param1 </param-name>          <param-value> An initialization parameter </param-value>       </init-param>    </servlet>    <servlet-mapping>       <servlet-name>HelloWorldPortlet</servlet-name>       <url-pattern>/HelloWorldPortlet/*</url-pattern>    </servlet-mapping> </web-app> 

DOCTYPE required

This will be the same for each and every web.xml deployed. This tag defines the DTD that is to be used when this document is parsed. Only one is allowed.

web-app required

This is the top-level tag wrapping the entity of the web.xml. Only one is allowed.

- id required

This attribute identifies the web-app in the application server but is not seen in the portal environment.

display-name required

Though this name is never seen in the portal environment, it will be seen in the WebSphere Administrator's console Event Message screen when the Web module is loaded. Only one is allowed.

context-param optional

This element provides an opportunity to set context parameters that will be shared by all portlets deployed via this Web application. Every portlet subsequently based on this web.xml will share access to the context parameters via the PortletContext object. There is no limit on the number of context parameters that may be set. These parameters cannot be changed at runtime by the administrator. For more information on parameters see "Parameter summary" on page 76.

param-name required

This indicates the name of the parameter. This name is used in code to retrieve the parameter value. For a summary on the various parameters set in the deployment descriptors, see "Parameter summary" on page 76.

param-value required

The String value held by the parameter.

servlet required

This tag wraps the definition of the servlet class. There must be one or more of these tags.

- id required

This provides an identifier for the defined servlet. This id will be used in the portlet.xml to refer to the defined class. The id must be unique within the Web application only.

servlet-name required

This name is not used by the portlet environment.

servlet-class required

The full class name must be provided. This class must be accessible either in the deployed war, via the application server library or through the classpath.

init-param optional

This element provides an opportunity to set parameters that will be shared by all portlets based on this servlet. These parameters are available in code through the PortletConfig object. There is no limit on the number of init parameters that may be set. These parameters cannot be changed at runtime by the administrator. For a summary on the various parameters set in the deployment descriptors, see "Parameter summary" on page 76.

param-name required

Indicates the name of the parameter. This name is used in code to retrieve the parameter value.

param-value required

The value held by the parameter.

servlet-mapping required

Though this element is not used by the portal environment it is a required element of the web-app element and therefore must be included.

servlet-name required

This is required and must be the same as the servlet name defined in the servlet element.

url-pattern required

This tag is required and may not be empty. The URL pattern is not used in the portal environment.

There are numerous other elements in traditional web.xml but they are not required in the portal environment.

2.6.2 portlet.xml

The portlet.xml elements are defined by the portlet_1.1.dtd which can be found in the WebSphere\PortalServer\app\wps.ear\wps.war\dtd directory. Figure 2-2 displays a simple portlet.xml.

Example 2-2. portlet.xml deployment descriptor
 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd"> <portlet-app-def>     <portlet-app uid="DCE:d798f9c6c:1" major-version="2" minor-version="1">         <portlet-app-name>HelloWorld application</portlet-app-name>         <portlet id="HWPortlet_1" href="WEB-INF/web.xml #Servlet_1"                           major-version="3" minor-version="2">             <portlet-name>HelloWorld portlet</portlet-name>             <cache>                 <expires>30</expires>                 <shared>yes</shared>             </cache>             <allows>                 <maximized/>                 <minimized/>             </allows>             <supports>                 <markup name="html">                     <view output="fragment"/>                     <configure/>                     <edit/>                     <help output="document"/>                 </markup>                 <markup name="wml">                     <view/>                 </markup>             </supports>         </portlet>     </portlet-app>     <concrete-portlet-app uid="DCE:d798f9c6c:1.1">         <portlet-app-name>HelloWorld application</portlet-app-name>         <context-param>             <param-name>context_param1</param-name>             <param-value>A context parameter</param-value>         </context-param>         <concrete-portlet href="#HWPortlet_1">             <portlet-name>HelloWorld portlet</portlet-name>             <default-locale>en</default-locale>             <language locale="en">                 <title>HelloWorld</title>                 <title-short>Hello</title-short>                 <description>A simple hello world portlet.</description>                 <keywords>Hello World simple</keywords>             </language>             <language locale="it">                 <title>ciao mondo</title>                 <title-short>ciao</title-short>                 <description>Un portlet semplice del mondo di ciao.                 </description>                 <keywords>Ciao mondo semplice.</keywords>             </language>             <language locale="es">                 <title>hola mundo</title>             </language>             <config-param>                 <param-name>config_param1</param-name>                 <param-value>A configuration parameter</param-value>             </config-param>         </concrete-portlet>     </concrete-portlet-app> </portlet-app-def> 

DOCTYPE required

This will be the same for each and every portlet.xml deployed. This tag defines the DTD that is to be used when this document is parsed. Only one is allowed.

portlet-app-def required

This is the top-level tag which encapsulates all abstract and concrete portlet application definitions. It is required and not more than one is allowed.

portlet-app required

This tag is used to define the abstract portlet application. This abstract application will be used as a basis for the concrete portlet applications defined later in the descriptor. Only one portlet-app tag is allowed per portlet.xml and only one portlet.xml is allowed per war file. Therefore, each war file may only deploy a single abstract portlet application.

- uid required

This ID uniquely identifies this abstract application in the portal server. This ID must unique throughout the entire portal environment. For guidelines on ensuring the ID is unique, refer to "UID guidelines" on page 77. This ID will be used if the portlet application is updated. Once the ID is determined, it should not be changed between iterations. Doing so will cause updates to fail. The ID may contain any combination of letters and characters to maximum length of 255.

- major-version optional

An optional tag only used by administrators to track releases; it is not used in the portal. It must be a number and only one is allowed. If this attribute is not supplied, the major-version will always be 0. If this attribute is supplied, the minor-version must also be included or the default value of 0 will be assumed.

- minor-version optional

An optional tag only used by the administrators to track releases and not used in the portal. Must be a number and only one is allowed. If this attribute is not supplied, the minor version will be 0. If this attribute is supplied, the major-version must also be included or the default value of 0 will be assumed.

portlet-app-name required

Only one is allowed. Since only concrete portlet applications are visible in the portal, this name is visible in the portal environment when the full information for the portal application is requested on the Manage Portlet Applications portlet. This name need not be unique.

portlet required

One or more of these tags is required. This tag defines the abstract portlets contained in the abstract portlet application. Each portlet tag maps to a single servlet defined in the web.xml. There is a one-to-one relationship between the servlets defined in the web.xml and the abstract portlets defined in the portlet.xml. You may not map two abstract portlets to the same servlet. Therefore, if there are two servlets defined in the web.xml, there will be two abstract portlets defined in the portlet.xml

- id required

This ID must be unique within the abstract portlet application only. This ID will be used by the concrete portlets to create a link to the abstract definition. It may be any combination of letters and numbers to a maximum of 64 characters.

- href required

This tag creates the link between the abstract portlet and the servlet defined in the web.xml. The link is formatted as in Example 2-3 where Servlet_1 is the ID defined in the <servlet id> tag of the web.xml.

Example 2-3. href syntax
 href="WEB-INF/web.xml#Servlet_1" 

- major-version optional

An optional tag only used by the administrators to track releases. Not used in the portal. Must be a number and only one is allowed. If this attribute is supplied, the minor-version must also be included or the default value of 0 will be assumed.

- minor-version optional

An optional tag only used by the administrators to track releases. Not used in the portal. Must be a number and only one is allowed. If this attribute is supplied, the major-version must also be included or the default value of 0 will be assumed.

portlet-name required

Defines the name of the abstract portlet. This name will only be seen in the show info screen of the Manage Portlet Application portlet, not during normal portlet administration or execution. Must be unique within the abstract portlet application only.

cache optional

This tag indicates the type and level of caching this portlet will perform. If this tag is included, it must contain the expires and shared elements. If the cache element is not included, the default values for expires and shared are 0 and no respectively.

expires required

Indicates in seconds the when the cached content should be considered expired .

- 0 indicates the content immediately expires and should always be refreshed

- -1 indicates the content does not expire.The content will not be refreshed once the portlet is initialized .

- Any other value measures the cache in seconds.

shared required

Indicates if the content is to shared among all users or if a cache must be maintained for each user. Use the NO option carefully as a large cache will result. Valid values are yes or no.

allows required

This tag indicates the portlet states that are supported by this portlet. The normal state is assumed and may not be unsupported. The other valid values are:

- maximized optional

When selected, the portlet will take ownership of the portal screen and other portlets will not be able to return content for inclusion in the portal page. Each portlet on the page will state have the opportunity to execute any listeners it implements, such as PortletPageListener. However, the service method, and by extension doView method of the other portlets will not be executed.

- minimized optional

When selected, the portlet will be displayed as a title bar only. Any listeners implemented by the portlet will be executed but the portlet's service, and by extension doView method will not.

- detached, moving, resizing, closed optional

Though these are valid values according to the DTD, they have no corresponding support in the portal server. As such, including or omitting them will have no effect at this point.

supports required

This element indicate which markup languages this portlet can render its content. It is required and at least one markup may be supported.

markup required

This tag provides a definition for a single markup that this portlet will support. Each markup that is to be supported is defined in a markup element.

- name required

This attribute identifies the name of the markup defined in this element. Valid strings are html, wml, chtml . If custom markups have been defined, they too would be valid.

view required

Indicates that at a minimum, this portlet supports View mode. This is required for all markup types.

- output optional

This attribute indicates the type of output the portal server should expect from this portlet. Valid values are document and fragment

  • Document : Not used in V4.1.2

  • Fragment : All HTML portlets should use this value.

configure optional

Indicates this portlet supports the Configure mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement configure support by including a doConfigure method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.

edit optional

Indicates this portlet supports the Edit mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement edit support by including a doEdit method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.

help optional

Indicates this portlet supports the Help mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement help support by including a doHelp method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.

concrete-portlet-app required

This element defines the concrete portlet application to be deployed into the portal server. One or more of these elements are required. This concrete application is based upon the abstract portlet application defined earlier in the portlet.xml. A concrete portlet application is not required to contain all of the portlets defined in the abstract application. However, it may not define more portlets than the abstract application. Each concrete portlet contained in the concrete application maps to one and only one abstract portlet. An abstract portlet may not be mapped twice in the same concrete application.

- uid required

This uid must be unique throughout the entire portal environment. Refer to 2.6.5, "UID guidelines" on page 77 for more information on ensuring UIDs are unique. This UID will be used by the portal server when the portlet is updated or deleted. If the ID changes between iterations, the original concrete application will not be update. Instead, a new concrete application will be installed, resulting in multiple concrete applications. Generally, once the ID has been determined, it should not be changed. The ID may contain any combination of letters and characters to a maximum length of 255.

portlet-app-name required

This is the application name that will be used in the portal server. When the war file is deployed, each of the concrete applications will be listed. This is the name that will appear in that list. This name need not be unique in the portlet.xml or the portal server. However, deploying more than one concrete portlet application with the same name may cause some administrative confusion. If two or more applications are deployed with the exact same name, only one will be initially active. The other application must be manually activated. In practice, when there is a one-to-one relationship between the abstract and concrete portlet applications, the application names are often the same. This name may contain any combination of letters and numbers to a maximum length of 255 and only one is allowed per concrete application.

context-param optional

This element provides an opportunity to set parameters that will be shared by all concrete portlets defined in the concrete portlet application. These parameters are available in code through the PortletApplicationSettings object. There is no limit on the number of context parameters that may be set. Be aware that these parameters may be changed at runtime by the administrator via the Manage Portlet Applications portlet. For a summary on the various parameters set in the deployment descriptors, see 2.6.3, "Parameter summary" on page 76.

param-name required

Indicates the name of the parameter. This name will be seen by the administrator if they decide to work with these parameters at runtime. This is also the name used in code to retrieve the parameter value. The name has a maximum length of 255.

param-value required

The value intended to be held by the parameter. This value can be changed at runtime by the administrator. The maximum length of the parameter value is 1048576.

concrete-portlet required

This element wraps the definition of the concrete portlet being deployed in this concrete application. Any number of concrete portlets may be deployed, up to the number of abstract portlets defined in the abstract portlet application.

- href required

This attribute creates a link between the concrete portlet and the abstract portlet. The syntax dictates that the portlet id defined in the abstract application be prefixed with a # symbol as illustrated in Example 2-4.

Example 2-4. Concrete portlet href
 <concrete-portlet href="#HWPortlet_1"> 

portlet-name required

This tag indicates the administrative name of the portlet. This name is not the title of the portlet and will not be seen by the average end user. This name need not be unique in the portlet.xml or the portal server. However, take care to properly name your portlets to prevent confusion. If two or more portlets are deployed in the same portlet.xml with the exact same name, only one will be initially active. The name may be any combination of characters to a maximum length of 255.

default-locale required

This element indicates which language is the default language for this concrete portlet alone. This setting will not override the user's preferred locale or locale settings provided by the client browser. If the client's locale cannot be determined, this value is used. Also, if the portlet does not support the locale requested by the user, this default locale is used instead. The value must be a recognized country code including, if appropriate, any variants. This value cannot be changed at runtime by the administrator.

language required

At least one language block must be included. Though not required, it is a best practice to ensure that at a minimum, the default locale is implemented in a language block. In practice, a language block should be provided for each language this portlet intends to support. ideally this includes all ten group 1 languages. Only the languages defined in the portlet.xml will be available. Though the strings can be changed, there is no mechanism to add new languages at runtime.

- locale required

This attribute indicates the locale being defined by this language block. The value must a recognized country code, including any applicable variants.

title required

This tag specifies the language specific title of this portlet. This title will be seen in the title bar of the portlet at runtime.This value may be changed at runtime by the administrator. The maximum length of the title is 255 characters.

title-short optional

This tag specifies the language specific short title of the portlet. The maximum length of the short title is 128.

description optional

This description is used in several places in the portal. For example, in the Edit Layout and Content portlet, the description will display in a hover box over the portlet. The maximum length for the description is 1024 characters.

keywords optional

This tag specifies the language specific keywords of the portlet. The maximum length of the keywords is 1024 characters.

config-param optional

This element allows parameters to be passed to the concrete portlet. Unlike context and servlet-config parameters, these parameters are not shared between portlets. Any number of portlet-config parameters may be supplied. The values can be changed at runtime by the administrator via the Manage Portlets portlet. These parameters are accessed in code via the PortletSettings object. For a summary on the various parameters set in the deployment descriptors, see "Parameter summary" on page 76.

param-name required

Indicates the name of the parameter. This name will be seen by the administrator if they decide to work with these parameters. This is also the name used in code to retrieve the parameter value. The name has a maximum length of 255.

param-value required

The value intended to be held by the parameter. This value can be changed at runtime by the administrator. The maximum length of the parameter value is 1048576.

2.6.3 Parameter summary

There are four types of parameters that can be specified in the deployment descriptors.

Parameter Name

Location

Visibility

Programmatic Access

Runtime Accessibility

Context-Param

web.xml-web app definition

Every portlet deployed in the.war

PortletContext.get InitParameter()

Read-only

Init-Param

web.xml-servlet definition

Each portlet based on the particular servlet

PortletConfig.getInitParameter() Portlet.getInitParameter()

Read-only

Context-Param

portlet.xml concrete app definition

All portlets defined in a single concrete app

PortletApplication Settings.getAttribute()

Read/Write

Config-Param

portlet-xml concrete portlet definition

Individual Concrete portlets

PortletSettings.getAttribute()

Read/Write

2.6.4 Descriptors relationship (web.xml and portlet.xml)

The relationship between servlets, abstract portlets and concrete portlets is best described in Figure 2-6 on page 77. Note that some required elements have been omitted for clarity.

Figure 2-6. web.xml and portlet.xml relationship

graphics/02fig06.gif

2.6.5 UID guidelines

When determining the UID for either concrete or abstract portlet applications there are several steps to follow to ensure the ID is guaranteed to be unique throughout the entire portal environment. It is recommended that your organization develop style guidelines to ensure uniqueness in your environment.

  • Include the portlet's namespace in the UID, using the same format that is used for Java packages

  • Add some portlet application specific description

  • Add some arbitrary characters to guarantee uniqueness within the namespace, for example: com.ibm.wps.samplet.mail.4969

  • Add postfixes for the corresponding concrete portlet applications, for example: com.ibm.wps.samplet.mail.4969

2.6.6 Building a war file

All the elements of the portlet need to be deployed in a Web archive (.war) file. This file can be created with any zip creation tool, the jar command line utility or the export utility of the WebSphere Studio Application Developer tool. The WebSphere Studio Application Developer environment will be covered in detail in Chapter 3, "Portal Toolkit" on page 125. Each war file should contain elements listed in Figure 2-7.

Figure 2-7. Basic WAR contents

graphics/02fig07.gif

The source folder is optional and you may choose what source to include for distribution.

The webApplication folder is optional and may be used to contain the WEB-INF folder. Alternatively, the WEB-INF folder can be placed directly under the root without modification.

Generally, it will also contain a JSP folder to hold all JSPs used throughout the entire portlet application. The JSP folder will organize the contained JSPs in folders representing the markup and languages they are intended to support. For example, if a portlet supported HTML, WML and cHTML and provided limited National Language support for HTML requests , the JSP folder would be organized as in Figure 2-8.

Figure 2-8. WAR structure for a portlet with NLS and multi-device support

graphics/02fig08.gif

The WEB-INF folder must contain at a minimum the two required deployment descriptors. The web.xml and portlet.xml must be placed directly under the WEB-INF folder.

The classes that make up the portlet application must be stored in one of two locations. Those classes that have been packaged into jar files should be stored in the lib directory. Classes that are not packaged in a jar file are stored in the classes folder with the complete package structure. Both approaches are illustrated in Figure 2-9.

Figure 2-9. Storing classes in the WEB-INF folder

graphics/02fig09.gif

Once the contents have been organized correctly, you can use the jar command line utility to create the war file. There is no compression requirement for the war file so you may choose to compress the file or not without affecting deployment. For a complete discussion regarding the jar utility, refer to:

http://java.sun.com/docs/books/tutorial/jar/basics/index.html

 <  Day Day Up  >  


IBM WebSphere Portal V5 A Guide for Portlet Application Development
IBM Websphere Portal V5: A Guide for Portlet Application Development
ISBN: 0738498513
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net