EDORAS FRAMEWORK

To use the defined spring beans, a context must be started. The context searches the classpath for all files named META-INF/*-applicationContext.xml and loads them. To ensure that the files are loaded in the right order, the @Id and @DependsOn annotations can be used:

<!---
    @Id("org.edorasframework.web")
    @DependsOn("org.edorasframework.core")
-->
<beans xmlns="http://www.springframework.org/schema/beans" ...
				

The code in the example ensures that the web component is loaded after the core component and therefore the web can overwrite bean definitions of the core.

In order for this dependency resolution to work, one has to use special spring context. See the javadoc for DependencyClassPathXmlApplicationContext , DependencyXmlWebApplicationContext and DependencyContextLoader .

To allow to use the same logging configuration during development and during maven builds on continuous integration servers edoras framework provides special log appenders / handlers.

The components listed below support the supported configuration possibilities to enable/ disable the logging.

# Root logger configuration
log4j.rootLogger=INFO, devel

# The development console appender
log4j.appender.devel=org.edorasframework.core.logging.DevelopmentConsoleAppender

# define whether logging is enabled or not
log4j.appender.devel.enableLogging=true

# the development console handler
handlers = org.edorasframework.core.logging.DevelopmentConsoleHandler

# Set the default logging level for the root logger
.level = ALL
    
# define whether logging is enabled or not
org.edorasframework.core.logging.DevelopmentConsoleHandler.enableLogging=true

If the description object implements the org.edorasframework.core.description.MutableDescription interface, some of the description's values may be changed at runtime. Using a persistent DAO, these changes will be available also after a restart of the application.

The application context of the edorasframework core module defines the following bewn names for the description provider beans.

If single descriptions are needed by configuration, the can be defined as follows:

<!--needs namespace: xmlns:core="http://schema.edorasframework.org/org.edorasframework.core"-->

<core:addDescription type="your.description.type.Class" key="1" value="Value" />

By using this tag, the description is automatically added to the description provider.

The org.edorasframework.core.description.impl.ListDescriptionResolver allows to define descriptions within the application context. The constructor argument of this resolver takes a list of description beans.

<bean class="org.edorasframework.core.description.impl.ListDescriptionResolver">
   <constructor-arg>
      <set>
         <!-- Description beans here -->
      </set>
   </constructor-arg>
</bean>

If descriptions are implemented as enumeration, the org.edorasframework.core.description.impl.EnumDescriptionResolver may be used to provide these descriptions to the description provider. As constructor argument the class name of the enumeration description implementation has to be defined.

<bean class="org.edorasframework.core.description.impl.EnumDescriptionResolver">
   <constructor-arg>
      <set>
         <!-- Enum Description class names here -->
      </set>
   </constructor-arg>
</bean>

If descriptions are defined as constants, the org.edorasframework.core.description.impl.ConstantDescriptionResolver may be used to provide these descriptions to the description provider. As constructor argument the class name of the enumeration description implementation has to be defined.

<bean class="org.edorasframework.core.description.impl.ConstantDescriptionResolver">
   <constructor-arg>
      <set>
         <!-- Enum Description class names here -->
      </set>
   </constructor-arg>
</bean>

The persistence unit post processor parses all classes handled by the entity manager factory and searches for the @Descriptions annotation. If such annotations are fount the resolver processes all defined description type classes and adds all descriptions automatically that are eighter defined as member variables or as enumeration of the description type class.

<bean id="entityManagerFactory" ...>
   <property name="persistenceUnitPostProcessors">
      <list>
         <ref bean="jpaDescriptionResolver" />
      </list>
   </property>
</bean>

<bean id="jpaDescriptionResolver" 
    class="org.edorasframework.core.description.impl.jpa.PersistenceUnitDescriptionResolver" />

To add description resolvers dynamically to the description provider the following tag can be used.

<!--needs namespace: xmlns:core="http://schema.edorasframework.org/org.edorasframework.core"-->

<core:addDescriptionResolver beanRef="resolverBeanId" />

The org.edorasframework.core.description.Descriptions annotation is used by the persistence unit description resolver. This annotation can be defined on the class or member field, to define which description types may be used by this specific class.

Description type classes can be annotated with the org.edorasframework.core.description.DescriptionType annotation to define a custom and user readable name for this description type.

<!-- Returns the description for the given type and key. If no description is found <code>null</code> is returned. -->
    <function>
        <function-name>description</function-name>
        <function-class>
            org.edorasframework.web.util.ELFunctions
        </function-class>
        <function-signature>
            org.edorasframework.core.description.Description getDescription(java.lang.String, java.lang.Integer)
        </function-signature>
    </function>

    <function>
        <function-name>descriptionTypeSelectItems</function-name>
        <function-class>
            org.edorasframework.web.util.ELFunctions
        </function-class>
        <function-signature>
            java.util.List getDescriptionSelectItems(java.lang.String,java.util.ResourceBundle,boolean)
        </function-signature>
    </function>

As an abbreviation for the word "internationalization" the i18n EL variable enables page authors to declaratively specify message keys. Currently the MessageContextImpl class will only get values that are provided the JSF standard message keys. Developers can use Spring to inject an alternate MessageContextImpl in order to leverage additional values.

<h:outputLabel value="#{The JSF required message is: i18n['javax.faces.component.UIInput.REQUIRED']}" />
				

The ext:inputFile tag renders an HTML <input type="file" /> tag which enables file upload capability.

<h:form enctype="multipart/form-data">
	<ext:inputFile value="#{modelManagedBean.file}" />
</h:form>
				

The ext:inputRichText tag renders a text area that provides the ability to enter rich text such as bold, italic, and underline. The renderer relies on the CKEditor^TM to provide the rich text editing area.

<ext:inputRichText id="comments" value="#{modelManagedBean.comments}" />
				

The ext:iceInfoDataPaginator encapsulates an ICEfaces ice:dataPaginator tag that renders pagination information for an associated ice:dataTable.

<f:view xmlns:ext="http://edorasframework.org/extfaces/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component">

	<ext:iceInfoDataPaginator for="dataTable1" />
	<ice:dataTable id="dataTable1" value="#{modelManagedBean.rows}" var="row">
		...
	</ice:dataTable>

</f:view>
				

The ext:iceInfoDataPaginator encapsulates an ICEfaces ice:dataPaginator tag that renders navigation controls for an associated ice:dataTable.

<f:view xmlns:ext="http://edorasframework.org/extfaces/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component">

	<ext:iceNavDataPaginator for="dataTable1" />
	<ice:dataTable id="dataTable1" value="#{modelManagedBean.rows}" var="row">
		...
	</ice:dataTable>

</f:view>
				

The ext:convertPhoneNumber tag converts a string of digits into a formatted phone number.

<h:inputText value="#{modelManagedBean.phoneNumber}">
	<ext:convertPhoneNumber unitedStatesPhoneFormat="###-###-####" />
</h:inputText>
				

The ext:convertYesNo tag converts input such as "Yes" and "No" to Boolean.TRUE and Boolean.FALSE respectively.

<h:inputText value="#{modelManagedBean.active}">
	<ext:convertYesNo />
</h:inputText>

The ext:validateEmailAddress tag validates an email address against the following regular expression: .+[@].+[.].+

<h:inputText value="#{modelManagedBean.emailAddress}">
	<ext:validateEmailAddress />
</h:inputText>
				

The Portlet 1.0 standard defines two lifecycle phases for the execution of a portlet that a compliant portlet container must support: The first is the javax.portlet.PortletRequest.RENDER_PHASE, in which the portlet container asks each portlet to render itself as a fragment of HTML. The second is the javax.portlet.PortletRequest.ACTION_PHASE, in which the portlet container invokes actions related to HTML form submission. When the portal receives an HTTP GET request for a portal page, the portlet container executes the portlet lifecycle and each of the portlets on the page undergoes the RENDER_PHASE. When the portal receives an HTTP POST request, the portlet container executes the portlet lifecycle and the portlet associated with the HTML form submission will first undergo the ACTION_PHASE before the RENDER_PHASE is invoked for all of the portlets on the page.

The Portlet 2.0 standard adds two more lifecycle phases that define the execution of a portlet. The first is the javax.portlet.PortletRequest.EVENT_PHASE, in which the portlet container broadcasts events that are the result of an HTML form submission. During this phase, the portlet container asks each portlet to process events that they are interested in. The typical use case for the EVENT_PHASE is to achieve Inter-Portlet Communication (IPC), whereby two or more portlets on a portal page share data in some way. The other new phase added by the Portlet 2.0 standard is the javax.portlet.PortletRequest.RESOURCE_PHASE, in which the portlet container asks a specific portlet to perform resource-related processing. One typical use case for the RESOURCE_PHASE is for an individual portlet to process Ajax requests. Another typical use case for the RESOURCE_PHASE is for an individual portlet to generate non-HTML content (for download purposes) such as a PDF or spreadsheet document.

The Portlet 1.0 and 2.0 standards define three portlet modes that a compliant portlet container must support: javax.portlet.PortletMode.VIEW, javax.portlet.PortletMode.EDIT, and javax.portlet.PortletMode.HELP. Portal vendors and portlet developers may supply custom modes as well. VIEW mode refers to the rendered portlet markup that is encountered by the user under normal circumstances. Perhaps a clearer name would be normal mode or typical mode, because the word view is also used by developers to review to the view concern of the MVC design pattern. EDIT mode refers to the rendered portlet markup that is encountered by the user when selecting custom values for portlet preferences. Perhaps a clearer name would be preferences mode. Finally, HELP mode refers to the rendered portlet markup that is encountered by the user when seeking help regarding the usage and/or functionality of the portlet.

Figure 6.2. Portlet VIEW Mode

Figure 6.3. Portlet EDIT Mode

Figure 6.4. Portlet HELP Mode

Portals typically manifest the rendered markup of a portlet in a rectangular section of the browser known as a portlet window. The Portlet 1.0 and 2.0 standards define three window states that a compliant portlet container must support: javax.portlet.WindowState.NORMAL, javax.portlet.WindowState.MAXIMIZED, and javax.portlet.WindowState.MINIMIZED. The NORMAL window state refers to the way in which the portlet container displays the rendered markup of a portlet when it can appear on the same portal page as other portlets. The MAXIMIZED window state refers to the way in which the portlet container displays the rendered markup of a portlet when it is the only portlet on a page, or when the portlet is to be rendered more prominently than other portlets on a page. Finally, the MINIMIZED window state refers to the way in which the portlet container displays a portlet when the markup is not to be rendered.

Developers often have the requirement to provide the end-user with the ability to personalize the portlet behavior in some way. To meet this requirement, the Portlet 1.0 and 2.0 standards provide the ability to define preferences for each portlet. Preference names and default values can be defined in the WEB-INF/portlet.xml configuration file. Portal end-users start out interacting with the portlet user interface in portlet VIEW mode but can switch to portlet EDIT mode in order to select custom preference values.

<portlet-app>
	<portlet>
		...
		<portlet-preferences>
			<preference>
				<name>datePattern</name>
				<value>MM/dd/yyyy</value>
			</preference>
			<preference>
				<name>unitedStatesPhoneFormat</name>
				<value>###-###-####</value>
			</preference>
		</portlet-preferences>
				...
	</portlet>
</portlet-app>

Inter-portlet communication (IPC) is a technique whereby two or more portlets on a portal page share data in some way. In a typical IPC use case, user interactions with one portlet affect the rendered markup of another portlet. The Portlet 2.0 standard provides two techniques to achieve IPC: Public Render Parameters and Server-Side Events.

The Public Render Parameters technique provides a way for portlets to share data by setting public/shared parameter names in a URL controlled by the portal. While the benefit of this approach is that it is relatively easy to implement, the drawback is that only small amounts of data can be shared. Typically the kind of data that is shared is simply the value of a database primary key.

The Server-Side Events technique provides a way for portlets to share data using an event-listener design. When using this form of IPC, the portlet container acts as broker and distributes events and payload (data) to portlets. One requirement of this approach is that the payload must implement the java.io.Serializable interface since it might be sent to a portlet in another WAR running in a different classloader.

It could be argued that the Portlet 2.0 approaches for IPC have a common drawback in that they can lead to a potentially disruptive end-user experience. This is because they cause either an HTTP GET or HTTP POST which results in a full page refresh. Technologies such as ICEfaces Ajax Push can be used to solve this problem.

Figure 6.5. Illustration of IPC

The Portlet 1.0 and JSF 1.0 specifications were formulated during roughly the same timeframe. Consequently, the JSF expert group was able to design a framework with portlet compatibility in mind. This is evidenced by methods like ExternalContext.getRequest() which returns a value of type Object, rather than a value of type javax.servlet.http.HttpServletRequest. When running inside a portlet container, the same method would return a value of type javax.portlet.PortletRequest. Although the JSF API provides a degree of portlet compatibility, it is necessary to introduce a bridge between the JSF lifecycle and the Portlet lifecycle in order to run JSF applications as portlets.

In order to use JSF in a portlet, developers must specify a JSF portlet bridge in the <portlet-class> element of the WEB-INF/portlet.xml descriptor. JSF portlet bridge implementations are either based on the JSR 301 standard, the JSR 329 standard, or were developed as innovative open source projects prior to the formulation of the standards. The JSR 301 standard defines a bridge API for Portlet 1.0 + JSF 1.2, whereas the JSR 329 standard defines a bridge API for Portlet 2.0 + JSF 1.2. The reference implementation for JSR 301 and 329 is the Apache MyFaces Portlet Bridge project.

JSF portlet bridges are responsible for providing a “bridge” between the portlet lifecycle and the JSF lifecycle. For example, when a portal page that contains a JSF portlet is requested via HTTP GET, then the RENDER_PHASE of the portlet lifecycle should in turn execute the RESTORE_VIEW and RENDER_RESPONSE phases of the JSF lifecycle. Similarly, when the user submits a form contained within a JSF portlet via HTTP POST, then the ACTION_PHASE of the portlet lifecycle should execute the complete JSF lifecycle of RESTORE_VIEW, APPLY_REQUEST_VALUES, PROCESS_VALIDATIONS, UPDATE_MODEL_VALUES, INVOKE_APPLICATION, and RENDER_RESPONSE.

Since the portal is in full control of managing URLs, JSF portlet bridges are also responsible for asking the portal to generate URLs that are compatible with actions that invoke JSF navigation rules. Consequently, JSF portlets may not perform a redirect. If a different JSF view is to be rendered as a result of a JSF navigation-rule, then the JSF portlet bridge simply displays the new JSF view in the same portlet window.

<portlet-app>
	<portlet>
		<portlet-name>my_portlet</portlet-name>
		<display-name>My Portlet</display-name>
		<portlet-class>
			javax.portlet.faces.GenericFacesPortlet
		</portlet-class>
		<init-param>
			<name>javax.portlet.faces.defaultViewId.view</name>
			<value>/xhtml/applicantForm.xhtml</value>
		</init-param>
		<init-param>
			<name>javax.portlet.faces.defaultViewId.edit</name>
			<value>/xhtml/edit.xhtml</value>
		</init-param>
		<init-param>
			<name>javax.portlet.faces.defaultViewId.help</name>
			<value>/xhtml/help.xhtml</value>
		</init-param>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>view</portlet-mode>
			<portlet-mode>edit</portlet-mode>
			<portlet-mode>help</portlet-mode>
		</supports>
		
		...
		
	</portlet>
</portlet-app>
			

<portlet-app>
	<portlet>
		<portlet-name>my_portlet</portlet-name>
		<display-name>My Portlet</display-name>
		<portlet-class>
			com.sun.faces.portlet.FacesPortlet
		</portlet-class>
		<init-param>
			<name>com.sun.faces.portlet.INIT_VIEW</name>
			<value>/xhtml/applicantForm.xhtml</value>
		</init-param>
		<init-param>
			<name>com.sun.faces.portlet.INIT_EDIT</name>
			<value>/xhtml/edit.xhtml</value>
		</init-param>
		<init-param>
			<name>com.sun.faces.portlet.INIT_HELP</name>
			<value>/xhtml/help.xhtml</value>
		</init-param>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>view</portlet-mode>
			<portlet-mode>edit</portlet-mode>
			<portlet-mode>help</portlet-mode>
		</supports>
		
		...
		
	</portlet>
</portlet-app>
			

The default view-handler for JSF 1.x is designed for JSP technology. With the advent of the Facelets view-handler, JSF developers were able to migrate away from JSP-based views to XHTML-based views and take advantage innovative features such as Composite Components and Page Templates. The Facelets project can be found at: https://facelets.dev.java.net

<faces-config>
	<application>
		<view-handler>
			com.sun.facelets.FaceletPortletViewHandler
		</view-handler>
	</application>
</faces-config>

JSF portlet developers often have the requirement to provide the end-user with the ability to personalize the portlet in some way. To meet this requirement, the Portlet 2.0 specification provides the ability to define portlet preferences for each portlet. Preference names and default values can be defined in the WEB-INF/portlet.xml descriptor. Portal end-users start out interacting with the portlet user interface in portlet VIEW mode but switch to portlet EDIT mode in order to select custom preference values.

<portlet-preferences>
	<preference>
		<name>unitedStatesPhoneFormat</name>
		<value>###-###-####</value>
	</preference>
	<preference>
		<name>datePattern</name>
		<value>MM/dd/yyyy</value>
	</preference>
	<preference>
		<name>recipientEmailAddress</name>
		<value>humanresources@some-company-domain.com</value>
	</preference>
</portlet-preferences>

Additionally, Portlet 2.0 provides the ability to specify support for EDIT mode in the WEB-INF/portlet.xml descriptor.

<supports>
	<mime-type>text/html</mime-type>
	<portlet-mode>view</portlet-mode>
	<portlet-mode>edit</portlet-mode>
</supports>

However, just because support portlet EDIT mode has been specified, it doesn't mean that the portlet container knows which JSF view should be rendered when the user enters portlet portlet EDIT mode. JSF portlet developers must specify the Facelet view that is to be displayed for each supported portlet mode. While JSR 301/329 defines a standard way of specifying views, non-standard bridges each have their own way.

<init-param>
	<name>javax.portlet.faces.defaultViewId.edit</name>
	<value>/edit.xhtml</value>
</init-param>

<init-param>
	<name>com.sun.faces.portlet.INIT_EDIT</name>
	<value>/edit.xhtml</value>
</init-param>

<init-param>
	<name>com.icesoft.faces.EDIT</name>
	<value>/edit.iface</value>
</init-param>

Facelet views that are designed to be used in portlet EDIT mode are typically forms that contain JSF component tags that enable the portlet end-user to select custom preference values that override the default values specified in the WEB-INF/portlet.xml descriptor. JSR 301/329 bridge implementations are required to provide an EL resolver that introduces the portletPreferences variable into the EL, which is a mutable java.util.Map that provides read/write access to each portlet preference. By utilizing the JSR 301/329 portletPreferences variable within an EL ValueExpression, portlet developers can declaratively bind the Facelet view to the portlet preference model data. In order to save the preferences, a backing bean must call the PortletPreferences.store() method.

<!--
This is a file named edit.xhtml that can be used for portlet EDIT mode.
It utilizes the JSR 301/329 portletPreferences EL variable for gaining
read/write access to javax.portlet.PortletPreferences.
-->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html">

	<h:form>
		<h:messages globalOnly="true" />
		<h:outputLabel for="datePattern" />
		<h:inputText id="datePattern" required="true" value="#{portletPreferences['datePattern'].value}" />
		<h:message for="datePattern" />
		<h:commandButton actionListener="#{backingManagedBean.savePreferences}" value="Save Preferences" />
	</h:form>

</f:view>

/**
* This is a JSF backing managed-bean that has a savePreferences action-listener.
*/
public class BackingManagedBean {

	public void savePreferences(ActionEvent actionEvent) {
		FacesContext facesContext = FacesContext.getCurrentInstance();
		ExternalContext externalContext = facesContext.getExternalContext();
		PortletRequest portletRequest = (PortletRequest) externalContext.getRequest();
		PortletPreferences portletPreferences = portletRequest.getPreferences();
		portletPreferences.store();
	}
}

Just as JSF web application developers rely on ExternalContext in order to get access to the Servlet API, JSF portlet developers also rely on ExternalContext in order to get access to the Portlet API. The two most common tasks that JSF portlet developers need to perform is to obtain an instance of the javax.portlet.PortletRequest or javax.portlet.PortletResponse objects.

public class BackingBean {

	public String submit() {
		FacesContext facesContext =
			FacesContext.getCurrentInstance();

		ExternalContext externalContext =
			facesContext.getExternalContext();

		PortletRequest portletRequest =
			(PortletRequest) externalContext.getRequest();

		PortletResponse portletResponse =
			(PortletResponse) externalContext.getResponse();

		return “success”;
	}
}
			

Facelet views that are designed to be used in portlet EDIT mode are typically forms that enable the portlet end-user to select custom preference values that override the default values specified in the WEB-INF/portlet.xml configuration file. JSR 301/329 bridge implementations are required to provide an EL resolver that introduces the portletPreferences variable into the EL, which is a mutable java.util.Map that provides read/write access to each portlet preference. By utilizing the JSR 301/329 portletPreferences variable within an EL ValueExpression, portlet developers can declaratively bind the Facelet view to the portlet preference model data. In order to save the preferences, a backing bean must call the javax.portlet.PortletPreferences.store() method.

<!--
	This is a file named edit.xhtml that can be used
	for portlet EDIT mode. It utilizes the JSR 301/329
	portletPreferences EL variable for gaining read/write
	access to javax.portlet.PortletPreferences.
-->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html">
	<h:form>
		<h:messages globalOnly="true" />
		<h:outputLabel for="datePattern" />
		<h:inputText id="datePattern"
			required="true"
			value="#{portletPreferences['datePattern'].value}" />
		<h:message for="datePattern" />
		<h:commandButton
			actionListener="#{backingBean.savePreferences}"
			value="Save Preferences" />
	</h:form>
</f:view>

/**
 * This is a JSF backing managed-bean that has a
 * savePreferences action-listener.
 */
public class BackingBean {

	public void savePreferences(ActionEvent actionEvent) {

		FacesContext facesContext =
			FacesContext.getCurrentInstance();

		ExternalContext externalContext =
			facesContext.getExternalContext();

		PortletRequest portletRequest =
			(PortletRequest) externalContext.getRequest();

		PortletPreferences portletPreferences =
			portletRequest.getPreferences();

		portletPreferences.store();
	}
}

The only JSF portlet bridges that can technically support Portlet 2.0 style IPC are those that subclass the Portlet 2.0 version of javax.portlet.GenericPortlet class. At the time of this writing, version 1.2.3 of the Sun OpenPortal JSF Portlet Bridge supports Public Render Parameters, and Server-Side Events will be supported in a subsequent version. Also at the time of this writing, the JSR 329 standard supports both Public Render Parameters and Server-Side Events. As the JSR 329 specification is currently only at Early Draft Review 2 (EDR2) status, please refer to the following sections of the specification for the latest details on how to leverage Portlet 2.0 IPC with JSF:

Perhaps the most natural approach for a JSF developer to try for IPC is to specify session scope on a JSF managed-bean. Surprisingly, this approach doesn’t work. To understand the reason why, it is necessary to discuss the fact that the Portlet 1.0 and 2.0 standards make a distinction between two kinds of session scopes: javax.portlet.PortletSession.APPLICATION_SCOPE and javax.portlet.PortletSession.PORTLET_SCOPE. The former can be used for sharing data between portlets packaged in the same WAR, but the latter cannot. The reason why JSF session scope can’t be used to share data between portlets is because all JSF portlet bridges use PortletSession.PORTLET_SCOPE.

In order to share data with PortletSession.APPLICATION_SCOPE, the JSF portlet developer can place a JSF model managed-bean in request scope and use the getter/setter as a layer of abstraction.

public class ModelManagedBean {

	public static final String
		SHARED_STRING_KEY = “sharedStringKey”;

	public String getSharedString() {
		return PortletSessionUtil.getSharedSessionAttribute(
			SHARED_STRING_KEY);
	}

	public void setSharedString(String value) {
		PortletSessionUtil.setSharedSessionAttribute(
			SHARED_STRING_KEY, value);
	}
}

public class PortletSessionUtil {

	public static Object getSharedSessionAttribute(
		String key) {

		FacesContext facesContext =
			FacesContext.getCurrentInstance();

		ExternalContext externalContext =
			facesContext.getExternalContext();

		PortletSession portletSession =
			(PortletSession) externalContext().getSession(false);

		return portletSession.getAttribute(
			key, PortletSession.APPLICATION_SCOPE);
	}

	public static void setSharedSessionAttribute(
		String key, Object value) {

		FacesContext facesContext =
			FacesContext.getCurrentInstance();

		ExternalContext externalContext =
			facesContext.getExternalContext();

		PortletSession portletSession =
			(PortletSession)externalContext().getSession(false);

		portletSession.setAttribute(
			key, value, PortletSession.APPLICATION_SCOPE);
	}
}

Alternatively, if using the Spring Framework to replace or augment the JSF Managed Bean Facility, then developers can store data in PortletSession.APPLICATION_SCOPE using the globalSession scope keyword

<bean
	id="sharedManagedBean"
	class="com.sample.jsf.SharedManagedBean"
	scope="globalSession"/>
			

When a portal page is requested for the first time via HTTP GET, portlets built with ICEfaces undergo the RENDER_PHASE of the portlet lifecycle just like any other portlet. From that point on, ICEfaces circumvents normal interaction through the portlet container. When doing a form submission from an ICEfaces portlet, an HTTP POST will not be performed; instead, form submission takes place via Ajax

There are two techniques that developers can use in order to enable Ajax in a JSF view built with ICEfaces component tags:

Note that if the first technique is used, then ICEfaces component tags that are used to perform full form submissions (such as ice:commandButton) must specify partialSubmit=”false”.

<?xml version="1.0" encoding="UTF-8"?>
<f:view xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.w3.org/1999/xhtml
	http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd">
	<ice:portlet>
		<ice:form partialSubmit="true">
			<ice:panelGrid columns=”2”>
<ice:outputLabel
for=”firstName” value=”First Name” />
<ice:inputText
	value=”#{modelManagedBean.firstName}” />
	<ice:message for=”firstName” />
	<ice:outputLabel
		for=”lastName” value=”Last Name” />
		<ice:inputText
		value=”#{modelManagedBean.lastName}” />
		<ice:message for=”lastName” />
			<ice:commandButton
			action=”#{backingManagedBean.submit}”
			partialSubmit=”false” />
			</ice:panelGrid>
		</ice:form>
	</ice:portlet>
</f:view>
			

Rather than writing markup directly to the response, ICEfaces components render themselves into a server-side Document Object Model (DOM) via the ICEfaces Direct-to-DOM (D2D) RenderKit. When a JSF view is requested for the first time, the markup inside the server-side DOM is delivered to the browser as part of the response. As the user interacts with the UI of the portlet, ICEfaces transparently submits user actions via Ajax and executes the JSF lifecycle. When the RENDER_RESPONSE phase of the JSF lifecycle completes, ICEfaces will compare the previous server-side DOM with the latest server-side DOM and send the incremental page updates back to the browser via the ICEfaces Ajax Bridge. In order to improve the application experience of the end-user, ICEfaces will only permit fields that have been visited by the user to undergo validation during the PROCESS_VALIDATIONS phase of the JSF lifecycle.

This approach is sometimes referred to as “dom-diffing” and provides the following benefits for portlets:

ICEfaces provides the ice:portlet component tag that developers should use to wrap the entire content of each portlet. It implements the javax.faces.component.NamingContainer interface so that it can apply the portlet namespace as the top level of the JSF ID hierarchy. Doing this makes the ID hierarchy more efficient and helps the ICEfaces framework uniquely identify components on the page, which is important when more than one ICEfaces portlet is placed on the same portal page.

ICEfaces 1.x ships with a Portlet 1.0 compliant portlet bridge for deployment of ICEfaces portlets. Note that ICEfaces 2.x will use a Portlet 2.0 compliant bridge that will include the ability to channel the ICEfaces Ajax requests through the Portlet 2.0 RESOURCE_PHASE of the portlet lifecycle.

<portlet-app>
	<portlet>
		<portlet-name>my_portlet</portlet-name>
		<display-name>My Portlet</display-name>
		<portlet-class>
			com.icesoft.faces.webapp.http.portlet.MainPortlet
		</portlet-class>
		<init-param>
			<name>com.icesoft.faces.portlet.viewPageURL</name>
			<value>/xhtml/applicantForm.xhtml</value>
		</init-param>
		<init-param>
			<name>com.icesoft.faces.portlet.editPageURL</name>
			<value>/xhtml/edit.xhtml</value>
		</init-param>
		<init-param>
			<name>com.icesoft.faces.portlet.helpPageURL</name>
			<value>/xhtml/help.xhtml</value>
		</init-param>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>view</portlet-mode>
			<portlet-mode>edit</portlet-mode>
			<portlet-mode>help</portlet-mode>
		</supports>
		
		...
		
	</portlet>
</portlet-app>
			

In order to use Facelets with the ICEfaces 1.x Portlet Bridge, it is necessary to use the ICEfaces com.icesoft.faces.facelets.D2DFaceletViewHandler class which is designed to provide support for Facelet views and the D2D RenderKit

<faces-config>
	<application>
		<view-handler>
			com.icesoft.faces.facelets.D2DFaceletViewHandler
		</view-handler>
	</application>
</faces-config>
			

Since ICEfaces 1.x portlets never perform an HTTP post, they do not participate in the ACTION_PHASE of the portlet lifecycle. It is therefore not possible for ICEfaces 1.x portlets to programmatically change the portlet window state. However, ICEfaces portlets can respond accordingly when the user clicks on links provided by the portal that control portlet window states.

ICEfaces provides a feature called Concurrent DOM Views that controls whether or not the ICEfaces framework supports multiple views of a single application from the same browser. When running in a portlet container, ICEfaces needs to treat the separate portlets on a single portal page as distinct views so it is almost always necessary (and therefore safest) to have this parameter set to true.

<context-param>
	<param-name>
		com.icesoft.faces.concurrentDOMViews
	</param-name>
	<param-value>true</param-value>
</context-param>
			

When developers specify a value of request for the scope a JSF managed-bean, the scope is understood to be very short-lived as it lasts for the duration of a request. When a developer specifies a value of request when using ICEfaces, then the ICEfaces Extended Request scope is applied by default. As an added benefit, the ICEfaces Extended Request scope lends itself quite well to portlets.

The ICEfaces Ajax Bridge is responsible for dispatching Ajax requests as a result of user-initiated actions and monitoring the status of each Ajax request. Developers can specify the com.icesoft.faces.connectionTimeout context parameter in the WEB-INF/web.xml configuration file to change the length of time (in milliseconds), that the ICEfaces Ajax Bridge will wait before declaring the connection lost. The default value is 60000 (60 seconds).

<context-param>
	<param-name>
		com.icesoft.faces.connectionTimeout
	</param-name>
	<param-value>80000</param-value>
</context-param>
			

The duration of the ICEfaces Extended Request scope begins when the view is first requested, and stays active until one of the following conditions occurs:

To disable the ICEfaces Extended Request scope, developers can specify the com.icesoft.faces.standardRequestScope context parameter in the WEB-INF/web.xml configuration file and set it to false.

<context-param>
	<param-name>
		com.icesoft.faces.standardRequestScope
	</param-name>
	<param-value>true</param-value>
</context-param>
			

While the Portlet 2.0 standard defines techniques for performing inter-portlet communication (IPC), they cause either an HTTP GET or HTTP POST which results in a full page reload and a disruptive end-user experience. ICEfaces provides a natural way for portlets to perform IPC via ICEfaces Ajax Push.

ICEfaces pioneered Ajax Push, which is sometimes referred to as Reverse Ajax or Comet. The technology provides the ability for server-initiated events to cause incremental page updates to be sent to the browser. With ICEfaces Ajax Push, developers can create collaborative and dynamic enterprise applications like never before.

Because the mechanism facilitates asynchronous updates from the server to the client, interaction with one ICEfaces portlet can trigger communication with other ICEfaces portlets by changing values in JSF backing and model managed-beans. This mechanism is not restricted to IPC among portlets on the same portal page in a single browser, but can include updating other browsers that are interacting with the same portal page. The result is not just inter-portlet communication, but inter-portlet, inter-browser communication. Additionally, ICEfaces Ajax Push solves the potentially disruptive end-user experience associated with the Portlet 2.0 standard IPC techniques.

Figure 6.6. Illustration of IPC with ICEfaces Ajax Push

The following is a list of guidelines for achieving IPC with ICEfaces Ajax Push

/*
* This is a file named ChatRoomManagedBean.java
* that is registered as a JSF managed-bean in
* application scope.
*/
import com.icesoft.faces.async.render.SessionRenderer;
import java.util.ArrayList;
import java.util.List;
import javax.faces.event.ActionEvent;

public class ChatRoomManagedBean {

	private String messageText;

	private List<String> messages = new ArrayList<String>();
	
	private static final String
		AJAX_PUSH_GROUP_NAME = "chatRoom";
	
	public ChatRoomsModel() {
		SessionRenderer.addCurrentSession(
			AJAX_PUSH_GROUP_NAME);
	}
	
	public void addMessage(ActionEvent actionEvent) {
		messages.add(messageText);
		SessionRenderer.render(AJAX_PUSH_GROUP_NAME);
	}
	
	public List<String> getMessages() {
		return messages;
	}
		
	public String getMessageText() {
		return messageText;
	}
		
	public void setMessageText(String messageText) {
		this.messageText = messageText;
	}
}
		
<!-- This is a Facelet view named chatRoom.xhtml -->
<?xml version="1.0" encoding="UTF-8"?>
<f:view xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.w3.org/1999/xhtml
	http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd">
	<ice:portlet>
		<ice:form>
			<ice:dataTable
				value=”#{chatRoomManagedBean.messages}”
				var=”message”>
				<ice:column>
					<ice:outputText value=”#{message}” />
				</ice:column>
			</ice:dataTable>
			<ice:inputText
				value=”#{chatRoomManagedBean.messageText}” />
			<ice:commandButton
				actionListener=”#{chatRoomManagedBean.addMessage}” />
		</ice:form>
	</ice:portlet>
</f:view>

The ICEfaces Component Suite fully supports consistent component styling via a set of predefined CSS style classes and associated images. Changing the component styles for a web application developed with the ICEfaces Component Suite is as simple as changing the style sheet used. ICEfaces ships with a set of predefined style sheets are available to be used as-is, or customized to meet the specific requirements of the application. There are five predefined ICEfaces style sheets included, two of which are designed to be used inside a portlet container:

<?xml version="1.0" encoding="UTF-8"?>
<f:view xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.w3.org/1999/xhtml
	http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd">
	<ice:portlet>
		<ice:outputStyle
			href="/xmlhttp/css/xp/xp-portlet.css" />
		<ice:form>
			...
		</ice:form>
	</ice:portlet>
</f:view>
			

The Portlet 1.0 and 2.0 standards document a set of common CSS class names that should be applied to specific page elements in order to integrate with the portlet container’s theme mechanism. When running in a portlet container, ICEfaces components will automatically render the following subset of Portlet 1.0 CSS class names where appropriate

To disable this feature, developers can specify the com.icesoft.faces.portlet.renderStyles context parameter in the WEB-INF/web.xml configuration file and set its value to false.

<context-param>
	<param-name>
		com.icesoft.faces.portlet.renderStyles
	</param-name>
	<param-value>false</param-value>
</context-param>
			

Liferay Portal supports styling for Portlet 1.0 and 2.0 standard CSS class names as well as a set of vendor-specific CSS class names within the context of a Liferay theme. However, since Liferay themes do not contain styling for the ICEfaces Component Suite, it is necessary to select an ICEfaces style sheet that is visually compatible with the Liferay theme.

On some occasions, it becomes necessary to override some of the styling in a Liferay theme in order to make it more visually compatible with an ICEfaces portlet. For example, Liferay themes typically render spans of class portlet-msg-error with a margin that has too much space to be placed alongside a rendered ice:inputText component tag.

<!--
	This is a file named my-portlet-view.xhtml
-->
<?xml version="1.0" encoding="UTF-8"?>
<f:view xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.w3.org/1999/xhtml
	http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd">
	<ice:portlet>
		<ice:outputStyle
			href="/xmlhttp/css/xp/xp-portlet.css" />
		<ice:outputStyle
			href="liferay-theme-override.css" />
		<ice:form styleClass=”my-portlet-view”>
			<ice:messages globalOnly=”true” />
			...
		</ice:form>
	</ice:portlet>
</f:view>

/*
 * This is a separate file named liferay-theme-override.css
 */
.my-portlet-view .portlet-msg-error {
	margin: 1px 0px 0px 0px;
	padding: 1px 5px 1px 24px;
}
			

When an ICEfaces portlet is added to a portal page at runtime by the end-user, the ICEfaces Ajax Bridge’s window.onload() logic will not be executed unless there is a full page refresh.

As a workaround, Liferay Portal provides configuration parameters that allow the developer to specify that a full page refresh is required. Doing this ensures that the ICEfaces bridge is properly initiated. The required parameters, render-weight and ajaxable, are specified in the WEB-INF/liferay-portlet.xml configuration file

<liferay-portlet-app>
	<portlet>
		<portlet-name>my_portlet</portlet-name>
		<instanceable>false</instanceable>
		<render-weight>1</render-weight>
		<ajaxable>false</ajaxable>
	</portlet>
</liferay-portlet-app>
			

In order to ensure compatibility with the Portlet 2.0 Technology Compatibility Kit (TCK), Liferay’s implementation of the javax.portlet.PortletRequest.getAttributeNames() method does not return a complete list of attribute names that are truly present in the PortletRequest object. Although certain attribute names are hidden, if they are known by the portlet developer, their respective values can be retrieved by calling Liferay’s implementation of the javax.portlet.PortletRequest.getAttribute(String name) method.

In order for the ICEfaces 1.x portlet bridge to maintain compatibility with the ICEfaces Extended Request scope, it needs to make a copy of all of the request attributes. In order to ensure that ICEfaces copies the necessary hidden attributes, developers must specify the com.icesoft.faces.portlet.hiddenAttributes context parameter in the WEB-INF/web.xml configuration file.

<context-param>
	<param-name>
		com.icesoft.faces.portlet.hiddenAttributes
	</param-name>
	<param-value>COMPANY_ID LAYOUT RENDER_PORTLET THEME_DISPLAY</param-value>
</context-param>
			

As an abbreviation for the word "internationalization", the i18n EL variable enables page authors to declaratively specify message keys that are provided by one of the following:

The Liferay Language Utility is typically accessed by portlet developers by calling static Java methods found in the LanguageUtil class. The utility operates by reading the locale-specific version of the portal's Language.properties file, which contains thousands of keys and internationalized messages.

Portlet developers can extend the Liferay Language Utility by creating a file within the portlet WAR named WEB-INF/liferay-hook.xml that points to locale-specific resource bundles that are in the runtime classpath of the portlet.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 5.2.0//EN" "http://www.liferay.com/dtd/liferay-hook_5_2_0.dtd">
<hook>
	<language-properties>Language_en_US.properties</language-properties>
</hook>

add-new-entry=Add New Entry
save-entry=Save Entry 

<h:outputLabel value="#{i18n['first-name']}" />

When using JBoss EL, page authors can take advantage of the i18n.replace() method in order to substitute values into the text of the message.

<!--
Note: The US English translation of the x-has-x-friends key would look like the following:
x-has-x-friends={0} has {1} friends.
-->
<h:outputText value="#{i18n.replace('x-has-x-friends', liferay.groupUser.fullName, friendsModel.dataModel.rowCount)}" />

This is a utility managed-bean that is designed to be kept in request scope. Its purpose is to introduce some Liferay-specific variables into the JSF EL. The reason why this is implemented as a managed-bean (and not as an ELResolver) is because of the way ICEfaces 1.x handles Ajax requests. When an ICEfaces portlet is first rendered to the portal page, the ICEfaces portlet bridge participates in a normal manner with the portlet lifecycle. However, all user interactions that trigger an Ajax XMLHttpRequest (like partialSubmit) bypass the portlet lifecycle and go directly to the ICEfaces PersistentFacesServlet. While this has great benefits for speed, it introduces problems when ICEfaces portlets need to interact with Liferay resources that are scoped to the portlet lifecycle. For example, the Liferay ThemeDisplay object is available as a request attribute in the portlet lifecycle, but when the lifecycle is complete, Liferay's ServicePostAction will call the ThemeDisplay.recycle() method which invalidates all of the properties. If the portlet utilizing this managed bean is an ICEfaces portlet, then ICEfaces will place the instance of this class in its "extended" request scope, which will keep the Liferay-specific values in existence long after the portlet lifecycle has completed. If the portlet is a standard JSF portlet, then the JSF managed-bean facility will place the instance of this class in standard request scope. This introduces a small amount of overhead for standard JSF portlets, but is necessary in order to have PortetFaces supply a standard API for both ICEfaces portlets and JSF portlets.

The Liferay companyId primary key value associated with the community/organization portal page that the current portlet is placed upon.

<h:outputText value="#{liferay.companyId} is the companyId associated with this set of Liferay Portal pages." />

The absolute URL for the Liferay Document Library Struts action path prefix. The most common use case is to append the /get_file suffix and some additional request parameters in order to provide a hyperlink to a document in the Liferay Document Library. See the Liferay struts-config.xml file for a complete list of available suffixes.

<h:dataTable id="documents" value="#{documentModelBean.dataModel}" var="dlFileEntry">
	<h:column>
		<f:facet name="head">
			<h:outputText value="#{i18n['file-name']}" />
		</f:facet>
		<h:outputLink
			target="_blank"
			value="#{liferay.documentLibraryURL}/get_file?p_l_id=#{liferay.themeDisplay.plid}&folderId=#{dlFileEntry.folderId}&name=#{dlFileEntry.name}">
			<h:outputText value="#{dlFileEntry.title}" />
		</h:outputLink>
	</h:column>
</h:dataTable>

The Liferay User that owns the Liferay community/organization portal page that the current portlet is placed upon.

<h:outputText
	value="The user named #{liferay.groupUser.fullName} owns this set of Liferay Portal pages." />

The absolute URL for the Liferay Image Gallery Struts action path prefix. See the Liferay struts-config.xml file for a complete list of available suffixes.

The absolute URL for the Liferay Image Servlet. Although this can be used to construct a URL that points a Liferay user's portrait/photo, for performance reasons, it is better to use the portraitURL EL variable instead.

The Liferay Layout associated with the community/organization portal page that the current portlet is placed upon.

<h:outputText
	value="The name of this portal page is #{liferay.layout.name}" />

The Liferay PermissionChecker associated with the current request and Liferay User.

<h:commandButton actionListener="#{backingBean.save}" rendered="#{liferay.permissionChecker.companyAdmin}" value="#{i18n['save']}" />

The absolute URL for the portal. For example: http://localhost:8080

The containing Liferay Portlet associated with the PortletRequest.

<h:outputText
	value="The name of this portlet is #{liferay.portlet.displayName}" />

Designed to be called from the EL by passing a Liferay User or userId as an array index, returns the absolute URL to the user's portrait.

<h:graphicImage value="#{liferay.portraitURL[liferay.group.user]}" />

Designed to be called from the EL by passing a Liferay service name String (bean id) as an array index, returns the instance of the service class. Liferay manages instances of services using Liferay-extended versions of the Spring XmlWebApplicationContext BeanFactory class named PortalApplicationContext and PortletApplicationContext. The liferay.service extension to the EL is meant to be used to resolve Liferay services so that they can be injected into JSF managed beans via the managed-property feature inside of the portlet's WEB-INF/faces-config.xml file.

<managed-bean>
	<managed-bean-name>modelManagedBean</managed-bean-name>
	<managed-bean-class>mypackage.ModelManagedBean</managed-bean-class>
	<managed-bean-scope>request</managed-bean-scope>
	<!-- Inject the service into the model managed bean. -->
	<managed-property>
		<property-name>myService</property-name>
		<value>#{liferay.service['myservice.bean.id']}</value>
	</managed-property>
</managed-bean>

The Liferay Theme associated with the Liferay Layout.

<h:outputText value="The name of the Liferay theme applied to this portal page is #{liferay.theme.name}" />

The Liferay ThemeDisplay associated with the PortletRequest. Perhaps it is easier to think of the Liferay ThemeDisplay as a "display context" which provides access to a wealth of information including the current Company, User, Layout, Theme, PermissionChecker, and more.

<link href="#{liferay.themeDisplay.uRLSignIn}">#{i18n['sign-in']}</link>

Designed to be called from the EL by passing a relative path to a theme image as an array index, returns the absolute URL to the theme image.

<h:graphicImage value="#{liferay.themeImageURL['/common/delete.png']}" />

Returns the absolute URL for the image path associated with the current Liferay Theme. For example: http://localhost:8080/image/image_gallery.

<h:graphicImage value="#{liferay.themeImagesURL}/common/delete.png" />

the Liferay User associated with the PortletRequest.

<h:outputText value="#{i18n['welcome']}, #{liferay.user.firstName}" />

Designed to be called from the EL by passing an action-key as an array index, returns a Boolean indicating whether or not the Liferay User associated with the PortletRequest has permission to execute the specified action-key on the current portlet. The action-key is typically defined in a Liferay resource-action-mapping XML file that defines the <portlet-resource/> and <model-resource/> permissions associated with a Liferay portlet. Please refer to the portal-impl/classes/resource-actions/messageboards.xml file in the Liferay Portal source code distribution for an example of how to write a Liferay resource-action-mapping XML file.

<h:dataTable
	rendered="#{liferay.userHasPortletPermission['VIEW']}"
	value="#{modelManagedBean.users}"
	var="user">
</h:dataTable>

The pf:inputFile tag renders an HTML <input type="file" /> tag which enables file upload capability.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:pf="http://portletfaces.org/facelets">

	<h:form enctype="multipart/form-data">
		<pf:inputFile value="#{managedBean.file}" />
		<h:commandButton action="#{fileUploadManagedBean.submit}" value="Upload File" />
	</h:form>

</f:view>

public class FileUploadManagedBean {

	private File file;

	public File getFile() {
		return file;
	}

	public void setFile(File file) {
		this.file = file;
	}

	public String submit( {
		System.out.println("Uploaded file: " + file);
		return "filesUploaded";
	}
}

The pf:inputRichText tag renders a text area that provides the ability to enter rich text such as bold, italic, and underline. The renderer relies on the CKEditor^TM to provide the rich text editing area.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:pf="http://portletfaces.org/facelets">

	<h:form>
		<pf:inputRichText id="comments" value="#{modelManagedBean.comments}" />
	</h:form>

</f:view>

The pf:permissionsLink tag renders an HTML anchor tag (hyperlink) that the user can click on in order to see the Liferay Permissions screen for the associated resource.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:pf="http://portletfaces.org/facelets">

	<h:form>
		<pf:permissionsLink
			modelResource="org.portletfaces.myproject.model.Book"
			modelResourceDescription="Book"
			resourcePrimKey="#{modelManagedBean.book.bookId} />
	</h:form>

</f:view>

The pf:iceInfoDataPaginator encapsulates an ICEfaces ice:dataPaginator tag that renders pagination information for an associated ice:dataTable. The navigation information will match the internationalized Liferay "showing-x-x-of-x-results" message.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:pf="http://portletfaces.org/facelets">

	<pf:iceInfoDataPaginator for="dataTable1" />
	<ice:dataTable id="dataTable1" value="#{modelManagedBean.rows}" var="row">
		...
	</ice:dataTable>

</f:view>

The pf:iceInfoDataPaginator encapsulates an ICEfaces ice:dataPaginator tag that renders navigation controls for an associated ice:dataTable. The icons will match the current Liferay theme.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:pf="http://portletfaces.org/facelets">

	<pf:iceNavDataPaginator for="dataTable1" />
	<ice:dataTable id="dataTable1" value="#{modelManagedBean.rows}" var="row">
		...
	</ice:dataTable>

</f:view>

The pf:icon tag encapsulates an HTML img tag whose src attribute contains a fully qualified URL to an icon image in the current Liferay theme.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:pf="http://portletfaces.org/facelets">

	<pf:icon alt="#{i18n['delete']}" image="delete" />

</f:view>

The pf:messages tag encapsualtes the h:messages tag and automatically applies the JSR 286 standard class names. See Liferay Theme Integration for more information.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:pf="http://portletfaces.org/facelets">

	<h:form>
		<pf:messages globalOnly="true" />
		<h:panelGrid columns="3">
			<h:outputLabel for="dateOfBirth" />
			<h:inputText id="dateOfBirth" value="#{modelManagedBean.dateOfBirth}" />
			<pf:messages for="dateOfBirth" />
		</h:panelGrid>
		<h:commandButton action="#{backingManagedBean.submit}" />
	</h:form>
	
</f:view>

The pf:message tag encapsualtes the h:message tag and automatically applies the JSR 286 standard class names. See Liferay Theme Integration for more information.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
	xmlns:ice="http://www.icesoft.com/icefaces/component"
	xmlns:pf="http://portletfaces.org/facelets">

	<h:form>
		<pf:messages globalOnly="true" />
		<h:panelGrid columns="3">
			<h:outputLabel for="dateOfBirth" />
			<h:inputText id="dateOfBirth" value="#{modelManagedBean.dateOfBirth}" />
			<pf:messages for="dateOfBirth" />
		</h:panelGrid>
		<h:commandButton action="#{backingManagedBean.submit}" />
	</h:form>

</f:view>

The pf:convertDateTime tag extends the default JSF date/time converter to support the output of Calendar, and takes the TimeZone and Locale of the current Liferay user into account.

<h:inputText value="#{modelManagedBean.calendar}">
	<pf:convertDateTime />
</h:inputText>

PortletFaces provides the PortletFacesContext.getThemeDisplay() method at the Java level and also the liferay.themeDisplay EL variable for getting access to the Liferay ThemeDisplay object.

PortletFaces provides the pf:icon Facelet composite component tag that encapsulates an HTML img tag whose src attribute contains a fully qualified URL to an icon image in the current Liferay theme. Additionally, PortletFaces provides the liferay.themeImagesURL and liferay.themeImageURL Facelet composite component tags for gaining access to theme image icons.

Most of the standard JSF HTML component tags render themselves as HTML markup such as <label />, <input />, <span />, etc. and assume the current Liferay theme thanks to the power of CSS. However, the h:messages and h:message tag will not assume the current Liferay theme unless the following JSR 286 standard CSS class names are applied:

<h:messages errorClass="portlet-msg-error" fatalClass="portlet-msg-error"
	infoClass="portlet-msg-info" warnClass="portlet-msg-warn" />
			

As a convenience, PortletFaces provides the pf:messages and pf:message Facelet composite component tags that encapsulate the h:messages and h:message tags respectively, and automatically apply the JSR 286 standard class names as shown above.

The org.edorasframework.test.common.executor.web.StartupTestServlet uses a test case executor to execute unit tests in an application server environment. This allows to run automated integration tests against productive databases using all layers of the application.

<!-- The servlet configuration -->
<servlet>
  <servlet-name>StartupTestServlet</servlet-name>
    <servlet-class>org.edorasframework.test.common.executor.web.StartupTestServlet</servlet-class>
    <init-param>
      <param-name>test.classes</param-name>
      <param-value>org.xyz.Test1;org.xyz.Test2;org.xyz.Test3</param-value>
    </init-param>
  <load-on-startup>10</load-on-startup>
</servlet>

<!-- The mapping for the test servlet -->
<servlet-mapping>
  <servlet-name>StartupTestServlet</servlet-name>
  <url-pattern>*.test</url-pattern>
</servlet-mapping>

An event can be raised by two different ways.

void raiseEvent(Event event) throws EventException;

void raiseEvent(String eventId, EventType type, Object bean, Object[] parameters) throws EventException;

void raiseEvent(String eventId, EventType type, Object bean, Object[] parameters, Object returnValue) throws EventException;

org.edorasframework.event.config.EventBeans.getEventBus();

@RaiseEvent(value = "demoEventId", type = EventType.ALWAYS)
public void demoMethod() {
    // your implementation here ...
}

To observe events this module provides two possibilities.

a void addEventlistener(String eventId, org.edorasframework.event.EventListener listener);

void onEvent(org.edorasframework.event.Event event);

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">
    
    <context-param>
        <param-name>contextClass</param-name>
        <param-value>
            org.edorasframework.web.config.DependencyXmlWebApplicationContext
        </param-value>
    </context-param>
    
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            classpath*:/META-INF/*-applicationContext.xml,
            /WEB-INF/applicationContext.xml
        </param-value>
    </context-param>
  
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>
            javax.faces.webapp.FacesServlet
         </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- bootstrap spring framework -->
    <servlet>
        <servlet-name>context</servlet-name>
        <servlet-class>
            org.springframework.web.context.ContextLoaderServlet
         </servlet-class>
        <!-- load the context servlet after the faces servlet -->
        <load-on-startup>2</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>
    
    <!-- spring support for request and session scope -->
    <listener>
        <listener-class>
            org.springframework.web.context.request.RequestContextListener
        </listener-class>
    </listener>
</web-app>
				

It basically defines the spring context, where to search the spring bean definitions and the servlets for JSF and spring.

<?xml version="1.0" encoding="UTF-8"?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
        http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
    version="1.2">
    
    <factory>
        <application-factory>
            org.edorasframework.web.util.JBossELApplicationFactory
        </application-factory>
    </factory>

    <application>
        <view-handler>
            com.icesoft.faces.facelets.D2DFaceletViewHandler
        </view-handler>
        <el-resolver>
            org.springframework.web.jsf.el.SpringBeanFacesELResolver
        </el-resolver>
    </application>
</faces-config>
				

It defines a special application factory that causes the JBoss EL implementation to be used, the facelets view handler and the spring bean EL resolver so that all spring beans can be accessed through EL expressions.

Definitions of the spring beans in the web part of the edoras framework.

One main goal of the web part of edoras framework is to facilitate the handling of entities. Default use cases should be as easy as possible. It provides some functions to use the entity handling of the core (see Section 2.3.1, “Entity handling” ).

After we have created an entity with @Label and validation annotations we can go on and create a view for it:

<html xmlns:web="http://www.edorasframework.org/taglib/org.edorasframework.web"
...
    <web:panel layout="simple">
        <web:textProperty value="#{person.firstName}" />
        <web:textProperty value="#{person.lastName}" />
        <web:property value="#{person.gender}">
            <h:selectOneRadio>
                <f:selectItem itemValue="MALE" itemLabel="male" />
                <f:selectItem itemValue="FEMALE" itemLabel="female" />
            </h:selectOneRadio>
        </web:property>
        <web:property value="#{person.birthday}">
            <h:inputText style="#{property.valid ? 'border: 1px solid green' : 'border: 1px solid red'}">
                <f:convertDateTime type="date"/>
            </h:inputText>
        </web:property>
    </web:panel>
...

Several things are going on here:

In the preceding sections, several tags provided by the edorasframework where shown. For a complete list of the available tags, see the taglibdoc section of the maven site of the web project.

Within the web module the view manager controller is by default session scoped.

<!-- Register the default view manager controller session scoped. -->
<bean id="edsViewManagerController" scope="session" 
   class="org.edorasframework.viewmanager.core.impl.DefaultViewManagerController"/>

<!-- Register the view manager phase listener -->
<bean id="edsViewManagerPhaseListener" class="org.edorasframework.viewmanager.web.impl.ViewManagerPhaseListener" />

This module registers also the viewManager phase listener automatically. The viewManager phase lsitener activates an deactivates the views as they are loaded within the session. To work properly the phase listener needs an the org.edorasframework.web.faces.listener.PhaseListenerBeanPostProcessor bean within the application context. This bean is by default initialized by the org.edorasframework.web module and needs only to be defined if the org.edorasframework.web is not used within the application.

web.xml

<servlet>
   <servlet-name>downloadServlet</servlet-name>
   <servlet-class>org.edorasframework.web.download.DownloadServlet</servlet-class>
   <load-on-startup>5</load-on-startup>
</servlet>

!-- cleans the uploaded files when the session is closed -->
<listener>
   <listener-class>org.edorasframework.filestore.icefaces.impl.InputFileSessionCleaner</listener-class>
</listener>

The org.edorasframework.filestore.core.mime.MimeTypeResolver is a component to resolve the mime type of a given file which is used by the file store. The mime type resolver can be injected into the default filestore service implementation, but is not needed. If no resolver is set the, mime type used will always be application/x-unknown.

The org.edorasframework.filestore.icefaces.impl.IcefacesFilestoreController uses the ICEfaces ICEfaces ice:inputFile component to enable the file upload to the server. Check the ICEfaces documentation to include and configure this component.

The org.edorasframework.filestore.web.impl.FilestoreDownloadHandler needs to be configured as spring bean. It is responsible that the requests of the downloadservlet are delegated to the filestoer service.

The filestore web module provides el functions to generate links for stored files. The links can be generated by using the hash id of the document. To use this functions, the namespace http://www.edorasframework.org/taglib/org.edorasframework.filestore.web has to be difined within your web template. The generated links include alreay the context name of the current application.

The function filestoreHashDownloadLink takes the String hash id of a document and retuns the the sownload link for the given document.

groupId: org.edorasframework.archetype

artifactId: org.edorasframework.archetype.edoras.module

This archetype creates a simple eclipse web project with three modules:

groupId: org.edorasframework.archetype

artifactId: org.edorasframework.archetype.edoras.module

This archetype creates a default edoras module containing the following three sub projects: