Portlet Development (JavaEE Development Version)¶

Table of Contents

Summary ¶

In this chapter procedures and remarks for creating portlets by using JavaEE Development Model are described.

In order to create a portlet, it is necessary to understand the contents of [Portlet Lifecycle] and decide which lifecycle should be used.

Screen Development (render cycle)

Screen to be displayed in the portlet is created. It can be switched by looking at mode or window status.

Screen for the display mode is always necessary.

Action Process (processAction cycle)

Process of data submitted from the portlet is created. Function container which was created is called an Action Handler, which
can be used by registering it on the Portlet Edit Screen.

It is also possible to link with another portlet by setting Event.

Event Process (processEvent cycle)

Receive Process for the event generated by another portlet is created. Function container which was created is called an Event Handler, which can be used by registering it on the Portlet Edit Screen.

Files that are created will vary depending on the lifecycle of portlet as below.

render mandatory JavaEE Development Model Screen. Main JSP and HelperBean.

processAction optional Java class which implemented handleAction PortletActionHandler interface.

processEvent optional Java class which implemented PortletEventHandler interface.

You can create programs for all lifecycles, and create 1 
	portlet by combining them.
You can do separate development for each lifecycle, and create 
	it for use by combining them among multiple portlets.
APIs available in the portlet and the implementation method in 
	each lifecycle are briefly described in the next sections.

Portlet API ¶

Portlet with just a simple screen display can be created 
	without using the Portelt API.  However, if you want to fully utilize 
	the functions of portlet,

	it is necessary to utilize the Portlet API.
Especially, for the Action process and Event process to be 
	executed, Portlet API must be used.
This document describes only the basic functions.
Please refer to [Portal API List] and [Portlet API2.0 
	Document] for information about all APIs.

You can get Portlet API2.0 document from below.

http://jcp.org/en/jsr/detail?id=286

PortalManager ¶

While PortletAPI2.0 can be used as is in JavaEE Development Model, PortalManager class is provided as an accessor to use API more easily.

jp.co.intra_mart.foundation.portal.common.PortalManager

Each function of PortalManager will be described when it is actually used in the following sections.

Portlet Mode ¶

Page type of the portlet created in JavaEE Development Model will be [im-JavaEE Service Framework].

Whether you can use portlet mode or not is set for each page type. In the initial state of [im-JavaEE Service Framework] portlet, modes other than
Display Mode are unavailable.

Obtaining Portlet Mode ¶

You can obtain current portlet mode using the API as follows.

As a portlet mode the constant of [javax.portlet.PortletMode] class below is obtained.

(ex.) PortletMode.VIEW, PortletMode.EDIT, PortletMode.HELP

javax.portlet.RenderRequest renderRequest = PortalManager.getRenderRequest();
javax.portletPortletMode portletMode = renderRequest.getPortletMode();

Window Status ¶

Obtaining Window Status ¶

Current portlet mode can be obtained as below using the API.

Constant of [javax.portlet.WindowState] class shown below is obtained as window status.

Portlet is not called when it is minimized, and therefore [WindowState.MINIMIZED] will not be obtained.

(ex.) WindowState.NORMAL, WindowState.MAXIMIZED, WindowState.MINIMIZED

javax.portlet.RenderRequest renderRequest = PortalManager. getRenderRequest();
javax.portlet.WindowState windowState = renderRequest. getWindowState();

Screen Development (render cycle)¶

In the render cycle screen is displayed in the similar way 
	normal Web page is displayed.
Screen development of JavaEE Development Model is basically 
	not different from the development of normal intra-mart screens.
Page argument that was set on the Portlet New 
	Registration/Edit Screen (Refer to [Portal Group Administrator Operations 
	Guide]) can be obtained

	by the getParameter method of HttpServletRequest  object.
Moreover, request parameters that were set in the Action 
	process and Event process in the next sections can be obtained by HttpServletRequest 
	object too.

RenderRequest, RenderResponse ¶

Unlike the requests of normal Web pages, request object and response object which are used by the portlet will use RenderRequest object and
RenderResponse object which are the dedicated objects for displaying portlet.

Information of portlet can be obtained by using these objects.

Obtaining RenderRequest and RenderResponse
RenderRequest renderRequest = PortalManager.getRenderRequest();
RenderResponse renderResponse = PortalManager.getRenderResponse();
Page argument can be obtained by using HttpServletRequest object (which is accessed by [request] keyword in JSP) too so that it can
be shared by the normal Web pages.
Obtaining Page Argument in JSP
<%
RenderRequest renderRequest = PortalManager.getRenderRequest();
  // value1 and value2 have the same value
  String value1 = request.getParameter("param1");
  String value2 = renderRequest.getParameter("param1");
%>
Current portlet mode and window status are obtained from RenderRequest.

Scope of RenderRequest¶

Scope of RenderRequest is different from the scope of request 
	of normal Web application.
All the portlets retain requests independently, and request 
	parameters for displaying portal screen are not inherited.
However, following parameters are set automatically by the 
	portlet container.

portal_cd Key of portal screen where portlet is placed.

portalKind
Portal type of portal screen where portlet is placed. Following values are obtained.

user User Portal

group Group Portal

In order to set the request parameters to the portlet, it is necessary to execute Action process or Event process.

Request parameters that were once set will be valid during the session duration until the next Action process or Event process is executed.

ActionURL, RenderURL ¶

In case you create the function in which Submit process is done from the portlet created by JavaEE Development Model and the Portal Screen is
displayed again after the process, submission to the following URLs would be necessary to communicate with the portlet container.

ActionURL URL to call Action function

RenderURL URL to re-display Portal Screen

They can be obtained by using PortalManager.
Obtaining ActionURL and RenderURL
PortletURL actionURL = PortalManager.createActionURL();
PortletURL renderURL = PortalManager.createRenderURL();

In the sample program below, Action process is called after the submission of portlet developed in JavaEE Development Model.

JSP
<%
  PortletURL actionURL = PortalManager.createActionURL();
%>

<form action="<%= actionURL.toString() %>" method="POST">

  <input type="text" name="param1" value="">
  <input type="submit" value="Execute">
</form>
[portal/desktop] path is assigned to the display of portal screen.

Therefore, portal screen can be re-displayed by submitting to the Service. However, since portal information cannot be
inherited in this case, please use the method shown above.

Submission to the Action URL is the only possible way to call Action process.

Please register Action Handler on the Portlet Administration Screen, and submit it to ActionURL on the presentation page.

If Action Handler is undefined, Portal Screen will be simply re-displayed.

ActionURL includes portal information, and data volume is large. Please specify POST for method.

How to Share Normal Screen and Portlet Screen ¶

Code that are commonly used and the code necessary only on the normal screen should be created as separate JSP pages.
And then, the JSP page for the normal screen should load the common page by using include tag.

Please be reminded that each API in the portlet cannot be used in this scenario.

<html>
<head>
  <link src="sample.css" type="text/css">

</head>
<body>
    <div>
        Header Display Information
  </div>
  <!-- Include Common Code -->
  <jsp:include page="sample/sample-portlet.jsp" flush="true"/>
    <div>
        Footer Display Information
  </div>
</body>
</html>

Action Process (processAction cycle)¶

Since there is no screen display in the processAction cycle, 
	only the Action handle class which implements PortletActionHandler interface 
	is created.
Then, Action Handler which was created on the portlet 
	administration screen is registered, and Action process is executed by 
	submitting it to ActionURL.
In the Action process, setting of RenderParamter, setting of PortletPreference, 
	and update process such as Event setting are made.

Creation of A ction Handler ¶

Shown below is the example of Action Handler that sets event.

Create Java class which implements PortletActionHandler interface, and define the function below.

(This Java class is called Action Handler.)
(ex.) sample.portal.SampleActionHandler.java
// 「PortletActionHandler」 Interface is implemented.
public class SampleActionHandler implements PortletActionHandler {
  public Serializable handleAction(String portletCd, ActionRequest request, ActionResponse response) {
    // Obtain Request Argument
    String value = request.getParameter("param1");
    // Set Event
    // In case event is sent to intramart portlet, use ImEvent object.
    // ImEvent.IM_QNAME is used for QName.
    ImEvent event = new ImEvent();
    event.setEvent(value);
    response.setEvent(ImEvent.IM_QNAME, event);
    return null;
  }
}
Action Handler may also use the function container created in Script Development Model which is used by render.

Event can be generated by the return of following values.

jp.co.intra_mart.foundation.portal.common.handler .ImEvent instance

java.util.Map instance ・・・Event that has the pair value with Map key

Others ・・・ judged as a character string. Event that has the same value with the key.

In order to generate the event to the IM Portlet, it is necessary to use ImEvent class or specify the key starting with ‘im_’.

Please refer to PortletActionHandler of [Portal API List] for detail.
Register Action Handler to the Portlet

<Portlet New Registration Screen>

Place the Screen created in [Screen Development (render cycle)] on the portal screen, and Call Action Process from Portlet.

Screen is re-displayed after the execution of Action process.

<Portal Screen - Action Process>

ActionRequest, ActionResponse ¶

Arguments of Action Handler are ActionRequest object and 
	ActionResponse object, which are the dedicated object for Action process.
By using these objects, request argument can be obtained and 
	event setting can be made.
Please refer to [Portlet API2.0 Document] for detail.

RenderParameter Setting ¶

Request parameter (RenderParameter), which can be obtained 
	when the screen is displayed, is set in the Action process or Event process.
Request parameter at the time of Action process call is stored 
	in ActionRequest, but it is not inherited to render cycle. 
	Therefore, it should

	be explicitly set if it is required.
Please note that all the RenderParameter that were previously 
	set are cleared when Action process is called.

(ex.) Setting of RenderParameter in processAction cycle

// In case Request Parameter is set
response.setRenderParameter("param1", "value1");
// In case Request Parameter is deleted
response.setRenderParameter("param2", null);

(ex.) Use of RenderParameter in render cycle

String value = request.getParamter("param1");

PortletPreferences Setting ¶

PortletPreferences is the storage area of portlet information 
	for each user.
In the portlet container of intra-mart Accel Platform, 
	information that was set in PortletPreferences is saved in the database.
Information which was set here can be accessed anytime when 
	the screen is displayed.

(ex.) Use of javax.portlet.PortletPreferences

			// Obtaining PortletPreferences
PortletPreferences preferences = request.getPreferences();
// Obtaining Information which was set in PortletPreferences
String value = preferences.getValue("key1", "Default Value");
// Set Information to PortletPreferences.
preferences.setValue("key1", "value1");
// Settle PortletPreferences.
//  If this process is not executed, information is not saved.
preferences.store();

Event Setting ¶

By setting this event you can notify the event occurrence to multiple portlets other than the portlet that accepted the Action process and pass the process.

(ex.) Event setting in processEvent cycle
response.setEvent(eventId, eventValue);

Available Action Handler ¶

intra-mart Accel Platform provides the Action Handler below as standard.

jp.co.intra_mart.foundation.portal.common.handler.DefaultPortletHandler¶

On the Portlet New Registration/Edit Screen, if you check the 
	Action Handler check box, this handler is set as the initial value.
This Action Handler obtains the value from the request 
	parameter, and generates the event using that key and value.
If you simply need to generate the event from the screen, you 
	can just use this handler and do not create the Action Handler.
Following request parameter is set to generate the event.

“portlet.event.” + any character string

By doing it, the event below will be created.

Property Name Contents

id arbitrary character string of request parameter key

value request parameter value

You can set multiple request parameters and generate multiple events.

Property Name	Contents
id	arbitrary character string of request parameter key
value	request parameter value

jp.co.intra_mart.foundation.portal.common.handler.SetRenderParameterHandler¶

Request parameters when the portal screen is displayed cannot be obtained from the process in the portlet, because its scope is different from the one for the portlet.

By setting this Action Handler, request parameters when the portal screen is displayed will be made available in the portlet.

Event Process (processEvent cycle)¶

Since there is no screen displayed in the processEvent cycle, only the Event Handler class that implements PortletEventHandler interface is created.

Event process will be executed by further registering the Event Handler created on the portlet administration screen and setting the event by the
Action process of any portlet.

In the Event process, setting of RenderParamter, setting of PortletPreferences, and update process such as event setting are made.

Creation of E vent Handler ¶

Shown below is the example of Event Handler which sets RenderParameter.

Create Java class which implements PortletEventHandler interface, and define the function below.
(This Java class is called Event Handler.)

(ex.) sample.portal.SampleEventHandler.java
// [PortletEventHandler] interface is implemented.
public class SampleEventHandler implements PortletEventHandler {
  public Serializable handleEvent(String portletCd, EventRequest request, EventResponse response) {
    // Obtaining Event Object
    // Event object used between intramart portlets will be [ImEvent].
    ImEvent event = (ImEvent) request.getEvent().getValue();
    // Set request parameter which is used for screen display
    response.setRenderParameter(event.getEventId(), event.getEvent());
    return null;
  }
}
Event Handler can also use function container created in the Script Development Model used by render.

You can further generate the event by setting the return value.

<*> Please be careful not to cause the loop in your design.
Register Event Handler to the Portlet.

<Portlet New Registration Screen>

Place the screen created by [Screen Development (render cycle) ] and the portlet which can call the event created by
[Action Process (processAction cycle)] on the Portal Screen, and calls the Action porcess from the portlet that sets the event.

Event Handler is executed by the Action process. Then, the screen will be re-displayed.

<Portal Screen - Event Process>

ImEvent Object ¶

For the Event object which is obtained by EventRequest, ImEvent object will be set between intramart portlets.

ImEvent object stores the following information.

Property Name Type Value

id String

Event ID which is set in Action process

If omitted, character string [ImEvent] is set.

value String

Value of event which is set in Action process

It is obtained as a character string even when the object is set.

source String Portlet code of the portlet which set the Event.

Property Name	Type	Value
id	String	Event ID which is set in Action process If omitted, character string [ImEvent] is set.
value	String	Value of event which is set in Action process It is obtained as a character string even when the object is set.
source	String	Portlet code of the portlet which set the Event.

EventRequest, EventResponse ¶

Arguments of Event Handler are the EventRequest object and 
	EventResponse object, which are the dedicated objects for event process.
You can obtain request arguments and set the events by using 
	these objects.
Please refer to [Portlet API2.0 Document] for detail.

RenderParameter Setting ¶

Request parameter which can be obtained when the screen is 
	displayed (RenderParameter) is set in the Action process or in the Event 
	process.
RenderParameter which was already set when the event process 
	was called is stored in EventRequest, and it is automatically 
	inherited to the render cycle

	unless any special process is made.
If it is not necessary to inherit it, it should be deleted 
	explicitly.

(ex.) Setting of RenderParameter in processEvent cycle
// In case request parameter is set
response.setRenderParameter("param1", "value1");
// In case request parameter is deleted
response.setRenderParameter("param2", null);
(ex.) Use of RenderParameter in render cycle
request.getParamter(eventId);

PortletPreferences Setting ¶

PortletPreferences is the storage area of portlet information for each user.

In the portlet container of intra-mart Accel Platform, information that was set in PortletPreferences is saved in the database.

Information which was set here can be accessed anytime when the screen is displayed.

(ex.) Use of java.portlet.PortletPreferences

// Obtaining PortletPreferences
PortletPreferences preferences = request.getPreferences();
// Obtaining Information which was set in PortletPreferences
String value = preferences.getValue("key1", "Default Value");
// Information is set in PortletPreferences.
preferences.setValue("key1", "value1");
// Settle PortletPreferences.
//  If this process is not executed, information is not saved.
preferences.store();

Event Setting ¶

By setting the event, you can notify the event occurrence to multiple portlets other than the portlet that accepted the Action process and pass the process.
However, please be aware that doing the event process within the event process would cause performance degradation, and may possibly cause the event loop.
So, it should be implemented carefully.

(ex.) Event setting in processEvent cycle
response.setEvent(eventId, eventValue);

About [Important Notice] Portlet ¶

In the portal module, [Important Notice] portlet is provided to display the generic new arrival information.

In this [Important Notice] portlet, following items are displayed as new arrival information.

Category that shows the type of New Arrival Information

Contents of New Arrival Information (Summary)

Delivery Date

Transition Information associated with the New Arrival Information (link)

If you want to display your own new arrival information in the [Important Notice] portlet, new arrival information should be added in the steps below.

Implement the Provider that obtains New Arrival Information.

Information displayed in the new arrival portlet is obtained from the provider that implements the interface below.

Provider Interface for General New Arrival Information

jp.co.intra_mart.foundation.portal.general_purpose_portlet.provider.NewArrivedProvider

Password history management information is displayed in the [Important Notice] portlet using the provider below.

Please refer to it when you implement your own provider.

Provider for Password History Management General New Arrival Information

jp.co.intra_mart.foundation.security.password.PasswordHistoryNewArrivedProvider

Please refer to [Portal API List] for details about provider interface and provider implementation.
Define Provider Implementation.
For information about the provider class implemented, the information below is defined in
<Storage Root>/public/storage/portal/system_notice.xml.

<Provider Setting File>

Element

Description

new-arrived-portlet/sort

It defines if the obtained new arrival information is sorted by category.

new-arrived-portlet/provider/provider-class

It defines the implementation class of provider.

new-arrived-portlet/provider/init-param

It defines initialization parameter which is set to the provider class.

Shown below is the example of setting file description.

<system_notice.xml>
<new-arrived-portlet>
  <sort>true</sort>
      :
      :
  <provider>
        <provider-class>
            sample.SampleProvider
        </provider-class>
        <init-param>
            <param-name>param1</param-name>
            <param-value>hogehoge</param-value>
        </init-param>
  </provider>
</new-arrived-portlet>
You can register multiple providers, and display multiple new arrival information on 1 portlet.

render	mandatory	JavaEE Development Model Screen. Main JSP and HelperBean.
processAction	optional	Java class which implemented handleAction PortletActionHandler interface.
processEvent	optional	Java class which implemented PortletEventHandler interface.

ActionURL	URL to call Action function
RenderURL	URL to re-display Portal Screen

Element	Description
new-arrived-portlet/sort	It defines if the obtained new arrival information is sorted by category.
new-arrived-portlet/provider/provider-class	It defines the implementation class of provider.
new-arrived-portlet/provider/init-param	It defines initialization parameter which is set to the provider class.