Uploaded image for project: 'PUBLIC - Liferay Documentation'
  1. PUBLIC - Liferay Documentation
  2. LRDOCS-5284

Document breaking changes regarding Portlet 3.0 API upgrade in Liferay Portal 7.1


    • Type: Task
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Fix Version/s: 7.1.x
    • Component/s: Core Infrastructure
    • Labels:


      This task involves updating the breaking changes document regarding the upgrade to the Portlet 3.0 API.

      What changed?

      Liferay Portal 7.1 CE GA1 with the Portlet 3.0 API dependency provided in the runtime classpath. Previous versions provided the Portlet 2.0 API.

      Full support for Portlet 3.0 will not be available until Liferay Portal 7.1 CE GA2 is released.

      Who is affected?

      In general, developers that are planning to upgrade custom portlets from earlier versions of Liferay portal.

      How should I update my code?

      JSP Considerations

      Portlet 3.0 is a binary-backward-compatible upgrade. This means that Java source that was built against portlet-api-2.0.0.jar is compatible at runtime. However, since JSP files are typically not compiled until the first request, they do not fall under the category of pre-compiled source.

      Specifically, if a JSP contains a Java scriptlet that calls MimeResponse.createActionURL() or MimeResponse.createRenderURL() then there is a possibility that the JSP will fail to compile or throw a ClassCastException at runtime. The reason is because the return type of these methods has changed.

      As an example, one of Liferay's sample portlets had to be changed from:

      <aui:form action="<%= renderResponse.createActionURL() %>" method="post" name="fm">


      <aui:form action="<%= (PortletURL)renderResponse.createActionURL() %>" method="post" name="fm">

      Upgrade Considerations

      In order to take advantage of new features in Portlet 3.0, it is necessary for developers to rebuild portlet projects against the portlet-api-3.0.0.jar dependency and "opt-in" by specifying version 3.0 in one of two ways:

      <portlet-app version="3.0">
              property = {
              service = Portlet.class

      In addition, developers will need to opt-in to new JSP features by specifying the Portlet 3.0 tag library in their JSP views. For example:

      <%@ taglib uri="http://xmlns.jcp.org/portlet_3_0"  prefix="portlet" %>

      Note that JSPs that opt-in with the new tag library might encounter JSP compilation problems in connection with the <portlet:defineObjects/> tag. Specifically, if JSPs reference variables with the following names in Java scriptlets, then a JSP compilation failure may occur:

      • actionParams
      • clientDataRequest
      • cookies
      • contextPath
      • locale
      • locales
      • mutableRenderParams
      • namespace
      • portletContext
      • portletMode
      • portletRequest
      • portletResponse
      • resourceParams
      • windowId
      • windowState
      • stateAwareResponse

      As an example, JSP scriptlets like the following will encounter a JSP compilation failure:

      PortletRequest portletRequest = (PortletRequest)request.getAttribute(JavaConstants.JAVAX_PORTLET_REQUEST);
      PortletResponse portletResponse = (PortletResponse)request.getAttribute(JavaConstants.JAVAX_PORTLET_RESPONSE);
      String namespace = AUIUtil.getNamespace(portletRequest, portletResponse);
      if (Validator.isNull(namespace)) {
      	namespace = AUIUtil.getNamespace(request);

      JSF Considerations

      A new version of Liferay Faces Bridge that supports Portlet 3.0 planned for release in Q4, 2018. Download and upgrade instructions will be made available at https://www.liferayfaces.org at that time.

      Why was this change made?

      This change was made in order to provide our customers and community with the latest features offered by the Portlet 3.0 Specification, released in early 2017.




            • Votes:
              0 Vote for this issue
              0 Start watching this issue


              • Created:


                Version Package